Debian Codegraph @

upstream/debian-unstable/man1/perlclib.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLCLIB 1"
58 .TH PERLCLIB 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perlclib \- Interacting with standard C library functions
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 The perl interpreter is written in C; XS code also expands to C.
68 Inevitably, this code will call some functions from the C library,
69 \&\f(CW\*(C`libc\*(C'\fR. This document gives some guidance on interfacing with that
70 library.
71 .PP
72 One thing Perl porters should note is that \fIperl\fR doesn't tend to use that
73 much of the C standard library internally; you'll see very little use of,
74 for example, the \fIctype.h\fR functions in there. This is because Perl
75 tends to reimplement or abstract standard library functions, so that we
76 know exactly how they're going to operate.
77 .SH "libc functions to avoid"
78 .IX Header "libc functions to avoid"
79 There are many many libc functions. Most of them are fair game to use,
80 but some are not. Some of the possible reasons are:
81 .IP \(bu 4
82 They likely will interfere with the perl interpreter's functioning,
83 such as its bookkeeping, or signal handling, or memory allocation,
84 or any number of harmful things.
85 .IP \(bu 4
86 They aren't implemented on all platforms, but there is an alternative
87 that is.
88 .Sp
89 Or they may be buggy or deprecated on some or all platforms.
90 .IP \(bu 4
91 They aren't suitable for multi-threaded operation, but there is an
92 alternative that is, and is just as easily usable.
93 .Sp
94 You may not expect your code to ever be used under threads, but code has
95 a way of being adapted beyond our initial expectations. If it is just
96 as easy to use something that can be used under threads, it's better to
97 use that now, just in case.
98 .IP \(bu 4
99 In functions that deal with strings, complications may arise because the
100 string may be encoded in different ways, for example in UTF\-8. For
101 these, it is likely better to place the string in a SV and use the Perl
102 SV string handling functions that contain extensive logic to deal with
103 this.
104 .IP \(bu 4
105 In functions that deal with numbers, complications may arise because the
106 numbers get too big or small, and what those limits are depends on the
107 current platform. Again, the Perl SV numeric data types have extensive
108 logic to take care of these kinds of issues.
109 .IP \(bu 4
110 They are locale-aware, and your caller may not want this.
111 .PP
112 The following commentary and tables give some functions in the first
113 column that shouldn't be used in C or XS code, with the preferred
114 alternative (if any) in the second column.
115 .SS Conventions
116 .IX Subsection "Conventions"
117 In the following tables:
118 .ie n .IP """~""" 3
119 .el .IP \f(CW~\fR 3
120 .IX Item "~"
121 marks the function as deprecated; it should not be used regardless.
122 .ie n .IP """t""" 3
123 .el .IP \f(CWt\fR 3
124 .IX Item "t"
125 is a type.
126 .ie n .IP """p""" 3
127 .el .IP \f(CWp\fR 3
128 .IX Item "p"
129 is a pointer.
130 .ie n .IP """n""" 3
131 .el .IP \f(CWn\fR 3
132 .IX Item "n"
133 is a number.
134 .ie n .IP """s""" 3
135 .el .IP \f(CWs\fR 3
136 .IX Item "s"
137 is a string.
138 .PP
139 \&\f(CW\*(C`sv\*(C'\fR, \f(CW\*(C`av\*(C'\fR, \f(CW\*(C`hv\*(C'\fR, etc. represent variables of their respective types.
140 .SS "File Operations"
141 .IX Subsection "File Operations"
142 Instead of the \fIstdio.h\fR functions, you should use the Perl abstraction
143 layer. Instead of \f(CW\*(C`FILE*\*(C'\fR types, you need to be handling \f(CW\*(C`PerlIO*\*(C'\fR
144 types. Don't forget that with the new PerlIO layered I/O abstraction
145 \&\f(CW\*(C`FILE*\*(C'\fR types may not even be available. See also the \f(CW\*(C`perlapio\*(C'\fR
146 documentation for more information about the following functions:
147 .PP
148 .Vb 1
149 \& Instead Of: Use:
150 \&
151 \& stdin PerlIO_stdin()
152 \& stdout PerlIO_stdout()
153 \& stderr PerlIO_stderr()
154 \&
155 \& fopen(fn, mode) PerlIO_open(fn, mode)
156 \& freopen(fn, mode, stream) PerlIO_reopen(fn, mode, perlio) (Dep\-
157 \& recated)
158 \& fflush(stream) PerlIO_flush(perlio)
159 \& fclose(stream) PerlIO_close(perlio)
160 .Ve
161 .SS "File Input and Output"
162 .IX Subsection "File Input and Output"
163 .Vb 1
164 \& Instead Of: Use:
165 \&
166 \& fprintf(stream, fmt, ...) PerlIO_printf(perlio, fmt, ...)
167 \&
168 \& [f]getc(stream) PerlIO_getc(perlio)
169 \& [f]putc(stream, n) PerlIO_putc(perlio, n)
170 \& ungetc(n, stream) PerlIO_ungetc(perlio, n)
171 .Ve
172 .PP
173 Note that the PerlIO equivalents of \f(CW\*(C`fread\*(C'\fR and \f(CW\*(C`fwrite\*(C'\fR are slightly
174 different from their C library counterparts:
175 .PP
176 .Vb 2
177 \& fread(p, size, n, stream) PerlIO_read(perlio, buf, numbytes)
178 \& fwrite(p, size, n, stream) PerlIO_write(perlio, buf, numbytes)
179 \&
180 \& fputs(s, stream) PerlIO_puts(perlio, s)
181 .Ve
182 .PP
183 There is no equivalent to \f(CW\*(C`fgets\*(C'\fR; one should use \f(CW\*(C`sv_gets\*(C'\fR instead:
184 .PP
185 .Vb 1
186 \& fgets(s, n, stream) sv_gets(sv, perlio, append)
187 .Ve
188 .SS "File Positioning"
189 .IX Subsection "File Positioning"
190 .Vb 1
191 \& Instead Of: Use:
192 \&
193 \& feof(stream) PerlIO_eof(perlio)
194 \& fseek(stream, n, whence) PerlIO_seek(perlio, n, whence)
195 \& rewind(stream) PerlIO_rewind(perlio)
196 \&
197 \& fgetpos(stream, p) PerlIO_getpos(perlio, sv)
198 \& fsetpos(stream, p) PerlIO_setpos(perlio, sv)
199 \&
200 \& ferror(stream) PerlIO_error(perlio)
201 \& clearerr(stream) PerlIO_clearerr(perlio)
202 .Ve
203 .SS "Memory Management and String Handling"
204 .IX Subsection "Memory Management and String Handling"
205 .Vb 1
206 \& Instead Of: Use:
207 \&
208 \& t* p = malloc(n) Newx(p, n, t)
209 \& t* p = calloc(n, s) Newxz(p, n, t)
210 \& p = realloc(p, n) Renew(p, n, t)
211 \& memcpy(dst, src, n) Copy(src, dst, n, t)
212 \& memmove(dst, src, n) Move(src, dst, n, t)
213 \& memcpy(dst, src, sizeof(t)) StructCopy(src, dst, t)
214 \& memset(dst, 0, n * sizeof(t)) Zero(dst, n, t)
215 \& memzero(dst, 0) Zero(dst, n, char)
216 \& free(p) Safefree(p)
217 \&
218 \& strdup(p) savepv(p)
219 \& strndup(p, n) savepvn(p, n) (Hey, strndup doesn\*(Aqt
220 \& exist!)
221 \&
222 \& strstr(big, little) instr(big, little)
223 \& memmem(big, blen, little, len) ninstr(big, bigend, little, little_end)
224 \& strcmp(s1, s2) strLE(s1, s2) / strEQ(s1, s2)
225 \& / strGT(s1,s2)
226 \& strncmp(s1, s2, n) strnNE(s1, s2, n) / strnEQ(s1, s2, n)
227 \&
228 \& memcmp(p1, p2, n) memNE(p1, p2, n)
229 \& !memcmp(p1, p2, n) memEQ(p1, p2, n)
230 .Ve
231 .PP
232 Notice the different order of arguments to \f(CW\*(C`Copy\*(C'\fR and \f(CW\*(C`Move\*(C'\fR than used
233 in \f(CW\*(C`memcpy\*(C'\fR and \f(CW\*(C`memmove\*(C'\fR.
234 .PP
235 Most of the time, though, you'll want to be dealing with SVs internally
236 instead of raw \f(CW\*(C`char *\*(C'\fR strings:
237 .PP
238 .Vb 6
239 \& strlen(s) sv_len(sv)
240 \& strcpy(dt, src) sv_setpv(sv, s)
241 \& strncpy(dt, src, n) sv_setpvn(sv, s, n)
242 \& strcat(dt, src) sv_catpv(sv, s)
243 \& strncat(dt, src) sv_catpvn(sv, s)
244 \& sprintf(s, fmt, ...) sv_setpvf(sv, fmt, ...)
245 .Ve
246 .PP
247 If you do need raw strings, some platforms have safer interfaces, and
248 Perl makes sure a version of these are available on all platforms:
249 .PP
250 .Vb 3
251 \& strlcat(dt, src, sizeof(dt)) my_strlcat(dt, src, sizeof(dt))
252 \& strlcpy(dt, src, sizeof(dt)) my_strlcpy(dt, src, sizeof(dt))
253 \& strnlen(s) my_strnlen(s, maxlen)
254 .Ve
255 .PP
256 Note also the existence of \f(CW\*(C`sv_catpvf\*(C'\fR and \f(CW\*(C`sv_vcatpvfn\*(C'\fR, combining
257 concatenation with formatting.
258 .PP
259 Sometimes instead of zeroing the allocated heap by using \fBNewxz()\fR you
260 should consider "poisoning" the data. This means writing a bit
261 pattern into it that should be illegal as pointers (and floating point
262 numbers), and also hopefully surprising enough as integers, so that
263 any code attempting to use the data without forethought will break
264 sooner rather than later. Poisoning can be done using the \fBPoison()\fR
265 macros, which have similar arguments to \fBZero()\fR:
266 .PP
267 .Vb 4
268 \& PoisonWith(dst, n, t, b) scribble memory with byte b
269 \& PoisonNew(dst, n, t) equal to PoisonWith(dst, n, t, 0xAB)
270 \& PoisonFree(dst, n, t) equal to PoisonWith(dst, n, t, 0xEF)
271 \& Poison(dst, n, t) equal to PoisonFree(dst, n, t)
272 .Ve
273 .SS "Character Class Tests"
274 .IX Subsection "Character Class Tests"
275 There are several types of character class tests that Perl implements.
276 All are more fully described in "Character classification" in perlapi and
277 "Character case changing" in perlapi.
278 .PP
279 The C library routines listed in the table below return values based on
280 the current locale. Use the entries in the final column for that
281 functionality. The other two columns always assume a POSIX (or C)
282 locale. The entries in the ASCII column are only meaningful for ASCII
283 inputs, returning FALSE for anything else. Use these only when you
284 \&\fBknow\fR that is what you want. The entries in the Latin1 column assume
285 that the non-ASCII 8\-bit characters are as Unicode defines them, the
286 same as ISO\-8859\-1, often called Latin 1.
287 .PP
288 .Vb 1
289 \& Instead Of: Use for ASCII: Use for Latin1: Use for locale:
290 \&
291 \& isalnum(c) isALPHANUMERIC(c) isALPHANUMERIC_L1(c) isALPHANUMERIC_LC(c)
292 \& isalpha(c) isALPHA(c) isALPHA_L1(c) isALPHA_LC(u )
293 \& isascii(c) isASCII(c) isASCII_LC(c)
294 \& isblank(c) isBLANK(c) isBLANK_L1(c) isBLANK_LC(c)
295 \& iscntrl(c) isCNTRL(c) isCNTRL_L1(c) isCNTRL_LC(c)
296 \& isdigit(c) isDIGIT(c) isDIGIT_L1(c) isDIGIT_LC(c)
297 \& isgraph(c) isGRAPH(c) isGRAPH_L1(c) isGRAPH_LC(c)
298 \& islower(c) isLOWER(c) isLOWER_L1(c) isLOWER_LC(c)
299 \& isprint(c) isPRINT(c) isPRINT_L1(c) isPRINT_LC(c)
300 \& ispunct(c) isPUNCT(c) isPUNCT_L1(c) isPUNCT_LC(c)
301 \& isspace(c) isSPACE(c) isSPACE_L1(c) isSPACE_LC(c)
302 \& isupper(c) isUPPER(c) isUPPER_L1(c) isUPPER_LC(c)
303 \& isxdigit(c) isXDIGIT(c) isXDIGIT_L1(c) isXDIGIT_LC(c)
304 \&
305 \& tolower(c) toLOWER(c) toLOWER_L1(c)
306 \& toupper(c) toUPPER(c)
307 .Ve
308 .PP
309 For the corresponding functions like \f(CWiswupper()\fR, \fIetc.\fR, use
310 \&\f(CWisUPPER_uvchr()\fR for non-locale; or \f(CWisUPPER_LC_uvchr()\fR for locale.
311 And use \f(CWtoLOWER_uvchr()\fR instead of \f(CWtowlower()\fR, \fIetc.\fR. There are
312 no direct equivalents for locale; best to put the string into an SV.
313 .PP
314 Don't use any of the functions like \f(CWisalnum_l()\fR. Those are
315 non-portable, and interfere with Perl's internal handling.
316 .PP
317 To emphasize that you are operating only on ASCII characters, you can
318 append \f(CW\*(C`_A\*(C'\fR to each of the macros in the ASCII column: \f(CW\*(C`isALPHA_A\*(C'\fR,
319 \&\f(CW\*(C`isDIGIT_A\*(C'\fR, and so on.
320 .PP
321 (There is no entry in the Latin1 column for \f(CW\*(C`isascii\*(C'\fR even though there
322 is an \f(CW\*(C`isASCII_L1\*(C'\fR, which is identical to \f(CW\*(C`isASCII\*(C'\fR; the
323 latter name is clearer. There is no entry in the Latin1 column for
324 \&\f(CW\*(C`toupper\*(C'\fR because the result can be non\-Latin1. You have to use
325 \&\f(CW\*(C`toUPPER_uvchr\*(C'\fR, as described in "Character case changing" in perlapi.)
326 .PP
327 Note that the libc caseless comparisons are crippled; Unicode
328 provides a richer set, using the concept of folding. If you need
329 more than equality/non\-equality, it's probably best to store your
330 strings in an SV and use SV functions to do the comparision. Similarly
331 for collation.
332 .SS "\fIstdlib.h\fP functions"
333 .IX Subsection "stdlib.h functions"
334 .Vb 1
335 \& Instead Of: Use:
336 \&
337 \& atof(s) my_atof(s) or Atof(s)
338 \& atoi(s) grok_atoUV(s, &uv, &e)
339 \& atol(s) grok_atoUV(s, &uv, &e)
340 \& strtod(s, &p) Strtod(s, &p)
341 \& strtol(s, &p, n) Strtol(s, &p, b)
342 \& strtoul(s, &p, n) Strtoul(s, &p, b)
343 .Ve
344 .PP
345 But note that these are subject to locale; see "Dealing with locales".
346 .PP
347 Typical use is to do range checks on \f(CW\*(C`uv\*(C'\fR before casting:
348 .PP
349 .Vb 9
350 \& int i; UV uv;
351 \& char* end_ptr = input_end;
352 \& if (grok_atoUV(input, &uv, &end_ptr)
353 \& && uv <= INT_MAX)
354 \& i = (int)uv;
355 \& ... /* continue parsing from end_ptr */
356 \& } else {
357 \& ... /* parse error: not a decimal integer in range 0 .. MAX_IV */
358 \& }
359 .Ve
360 .PP
361 Notice also the \f(CW\*(C`grok_bin\*(C'\fR, \f(CW\*(C`grok_hex\*(C'\fR, and \f(CW\*(C`grok_oct\*(C'\fR functions in
362 \&\fInumeric.c\fR for converting strings representing numbers in the respective
363 bases into \f(CW\*(C`NV\*(C'\fRs. Note that \fBgrok_atoUV()\fR doesn't handle negative inputs,
364 or leading whitespace (being purposefully strict).
365 .SS "Miscellaneous functions"
366 .IX Subsection "Miscellaneous functions"
367 You should not even \fBwant\fR to use \fIsetjmp.h\fR functions, but if you
368 think you do, use the \f(CW\*(C`JMPENV\*(C'\fR stack in \fIscope.h\fR instead.
369 .PP
370 .Vb 10
371 \& ~asctime() Perl_sv_strftime_tm()
372 \& ~asctime_r() Perl_sv_strftime_tm()
373 \& chsize() my_chsize()
374 \& ~ctime() Perl_sv_strftime_tm()
375 \& ~ctime_r() Perl_sv_strftime_tm()
376 \& ~cuserid() DO NOT USE; see its man page
377 \& dirfd() my_dirfd()
378 \& duplocale() Perl_setlocale()
379 \& ~ecvt() my_snprintf()
380 \& ~endgrent_r() endgrent()
381 \& ~endhostent_r() endhostent()
382 \& ~endnetent_r() endnetent()
383 \& ~endprotoent_r() endprotoent()
384 \& ~endpwent_r() endpwent()
385 \& ~endservent_r() endservent()
386 \& ~endutent() endutxent()
387 \& exit(n) my_exit(n)
388 \& ~fcvt() my_snprintf()
389 \& freelocale() Perl_setlocale()
390 \& ~ftw() nftw()
391 \& getenv(s) PerlEnv_getenv(s)
392 \& ~gethostbyaddr() getaddrinfo()
393 \& ~gethostbyname() getnameinfo()
394 \& ~getpass() DO NOT USE; see its man page
395 \& ~getpw() getpwuid()
396 \& ~getutent() getutxent()
397 \& ~getutid() getutxid()
398 \& ~getutline() getutxline()
399 \& ~gsignal() DO NOT USE; see its man page
400 \& localeconv() Perl_localeconv()
401 \& mblen() mbrlen()
402 \& mbtowc() mbrtowc()
403 \& newlocale() Perl_setlocale()
404 \& pclose() my_pclose()
405 \& popen() my_popen()
406 \& ~pututline() pututxline()
407 \& ~qecvt() my_snprintf()
408 \& ~qfcvt() my_snprintf()
409 \& querylocale() Perl_setlocale()
410 \& int rand() double Drand01()
411 \& srand(n) { seedDrand01((Rand_seed_t)n);
412 \& PL_srand_called = TRUE; }
413 \& ~readdir_r() readdir()
414 \& realloc() saferealloc(), Renew() or Renewc()
415 \& ~re_comp() regcomp()
416 \& ~re_exec() regexec()
417 \& ~rexec() rcmd()
418 \& ~rexec_af() rcmd()
419 \& setenv(s, val) my_setenv(s, val)
420 \& ~setgrent_r() setgrent()
421 \& ~sethostent_r() sethostent()
422 \& setlocale() Perl_setlocale()
423 \& setlocale_r() Perl_setlocale()
424 \& ~setnetent_r() setnetent()
425 \& ~setprotoent_r() setprotoent()
426 \& ~setpwent_r() setpwent()
427 \& ~setservent_r() setservent()
428 \& ~setutent() setutxent()
429 \& sigaction() rsignal(signo, handler)
430 \& ~siginterrupt() rsignal() with the SA_RESTART flag instead
431 \& signal(signo, handler) rsignal(signo, handler)
432 \& ~ssignal() DO NOT USE; see its man page
433 \& strcasecmp() a Perl foldEQ\-family function
434 \& strerror() sv_string_from_errnum()
435 \& strerror_l() sv_string_from_errnum()
436 \& strerror_r() sv_string_from_errnum()
437 \& strftime() Perl_sv_strftime_tm()
438 \& strtod() my_strtod() or Strtod()
439 \& system(s) Don\*(Aqt. Look at pp_system or use my_popen.
440 \& ~tempnam() mkstemp() or tmpfile()
441 \& ~tmpnam() mkstemp() or tmpfile()
442 \& tmpnam_r() mkstemp() or tmpfile()
443 \& uselocale() Perl_setlocale()
444 \& vsnprintf() my_vsnprintf()
445 \& wctob() wcrtomb()
446 \& wctomb() wcrtomb()
447 \& wsetlocale() Perl_setlocale()
448 .Ve
449 .PP
450 The Perl-furnished alternatives are documented in perlapi, which you
451 should peruse anyway to see what all is available to you.
452 .PP
453 The lists are incomplete. Think when using an unlisted function if it
454 seems likely to interfere with Perl.
455 .SH "Dealing with locales"
456 .IX Header "Dealing with locales"
457 Like it or not, your code will be executed in the context of a locale,
458 as are all C language programs. See perllocale. Most libc calls are
459 not affected by the locale, but a surprising number are:
460 .PP
461 .Vb 10
462 \& addmntent() getspent_r() sethostent()
463 \& alphasort() getspnam() sethostent_r()
464 \& asctime() getspnam_r() setnetent()
465 \& asctime_r() getwc() setnetent_r()
466 \& asprintf() getwchar() setnetgrent()
467 \& atof() glob() setprotoent()
468 \& atoi() gmtime() setprotoent_r()
469 \& atol() gmtime_r() setpwent()
470 \& atoll() grantpt() setpwent_r()
471 \& btowc() iconv_open() setrpcent()
472 \& catopen() inet_addr() setservent()
473 \& ctime() inet_aton() setservent_r()
474 \& ctime_r() inet_network() setspent()
475 \& cuserid() inet_ntoa() sgetspent_r()
476 \& daylight inet_ntop() shm_open()
477 \& dirname() inet_pton() shm_unlink()
478 \& dprintf() initgroups() snprintf()
479 \& endaliasent() innetgr() sprintf()
480 \& endgrent() iruserok() sscanf()
481 \& endgrent_r() iruserok_af() strcasecmp()
482 \& endhostent() isalnum() strcasestr()
483 \& endhostent_r() isalnum_l() strcoll()
484 \& endnetent() isalpha() strerror()
485 \& endnetent_r() isalpha_l() strerror_l()
486 \& endprotoent() isascii() strerror_r()
487 \& endprotoent_r() isascii_l() strfmon()
488 \& endpwent() isblank() strfmon_l()
489 \& endpwent_r() isblank_l() strfromd()
490 \& endrpcent() iscntrl() strfromf()
491 \& endservent() iscntrl_l() strfroml()
492 \& endservent_r() isdigit() strftime()
493 \& endspent() isdigit_l() strftime_l()
494 \& err() isgraph() strncasecmp()
495 \& error() isgraph_l() strptime()
496 \& error_at_line() islower() strsignal()
497 \& errx() islower_l() strtod()
498 \& fgetwc() isprint() strtof()
499 \& fgetwc_unlocked() isprint_l() strtoimax()
500 \& fgetws() ispunct() strtol()
501 \& fgetws_unlocked() ispunct_l() strtold()
502 \& fnmatch() isspace() strtoll()
503 \& forkpty() isspace_l() strtoq()
504 \& fprintf() isupper() strtoul()
505 \& fputwc() isupper_l() strtoull()
506 \& fputwc_unlocked() iswalnum() strtoumax()
507 \& fputws() iswalnum_l() strtouq()
508 \& fputws_unlocked() iswalpha() strverscmp()
509 \& fscanf() iswalpha_l() strxfrm()
510 \& fwprintf() iswblank() swprintf()
511 \& fwscanf() iswblank_l() swscanf()
512 \& getaddrinfo() iswcntrl() syslog()
513 \& getaliasbyname_r() iswcntrl_l() timegm()
514 \& getaliasent_r() iswdigit() timelocal()
515 \& getdate() iswdigit_l() timezone
516 \& getdate_r() iswgraph() tolower()
517 \& getfsent() iswgraph_l() tolower_l()
518 \& getfsfile() iswlower() toupper()
519 \& getfsspec() iswlower_l() toupper_l()
520 \& getgrent() iswprint() towctrans()
521 \& getgrent_r() iswprint_l() towlower()
522 \& getgrgid() iswpunct() towlower_l()
523 \& getgrgid_r() iswpunct_l() towupper()
524 \& getgrnam() iswspace() towupper_l()
525 \& getgrnam_r() iswspace_l() tzname
526 \& getgrouplist() iswupper() tzset()
527 \& gethostbyaddr() iswupper_l() ungetwc()
528 \& gethostbyaddr_r() iswxdigit() vasprintf()
529 \& gethostbyname() iswxdigit_l() vdprintf()
530 \& gethostbyname2() isxdigit() verr()
531 \& gethostbyname2_r() isxdigit_l() verrx()
532 \& gethostbyname_r() localeconv() versionsort()
533 \& gethostent() localtime() vfprintf()
534 \& gethostent_r() localtime_r() vfscanf()
535 \& gethostid() MB_CUR_MAX vfwprintf()
536 \& getlogin() mblen() vprintf()
537 \& getlogin_r() mbrlen() vscanf()
538 \& getmntent() mbrtowc() vsnprintf()
539 \& getmntent_r() mbsinit() vsprintf()
540 \& getnameinfo() mbsnrtowcs() vsscanf()
541 \& getnetbyaddr() mbsrtowcs() vswprintf()
542 \& getnetbyaddr_r() mbstowcs() vsyslog()
543 \& getnetbyname() mbtowc() vwarn()
544 \& getnetbyname_r() mktime() vwarnx()
545 \& getnetent() nan() vwprintf()
546 \& getnetent_r() nanf() warn()
547 \& getnetgrent() nanl() warnx()
548 \& getnetgrent_r() nl_langinfo() wcrtomb()
549 \& getprotobyname() openpty() wcscasecmp()
550 \& getprotobyname_r() printf() wcschr()
551 \& getprotobynumber() psiginfo() wcscoll()
552 \& getprotobynumber_r() psignal() wcsftime()
553 \& getprotoent() putpwent() wcsncasecmp()
554 \& getprotoent_r() putspent() wcsnrtombs()
555 \& getpw() putwc() wcsrchr()
556 \& getpwent() putwchar() wcsrtombs()
557 \& getpwent_r() regcomp() wcstod()
558 \& getpwnam() regexec() wcstof()
559 \& getpwnam_r() res_nclose() wcstoimax()
560 \& getpwuid() res_ninit() wcstold()
561 \& getpwuid_r() res_nquery() wcstombs()
562 \& getrpcbyname_r() res_nquerydomain() wcstoumax()
563 \& getrpcbynumber_r() res_nsearch() wcswidth()
564 \& getrpcent_r() res_nsend() wcsxfrm()
565 \& getrpcport() rpmatch() wctob()
566 \& getservbyname() ruserok() wctomb()
567 \& getservbyname_r() ruserok_af() wctrans()
568 \& getservbyport() scandir() wctype()
569 \& getservbyport_r() scanf() wcwidth()
570 \& getservent() setaliasent() wordexp()
571 \& getservent_r() setgrent() wprintf()
572 \& getspent() setgrent_r() wscanf()
573 .Ve
574 .PP
575 (The list doesn't include functions that manipulate the locale, such as
576 \&\f(CWsetlocale()\fR.)
577 .PP
578 If any of these functions are called directly or indirectly from your
579 code, you are affected by the current locale.
580 .PP
581 The first thing to know about this list is that there are better
582 alternatives to many of the functions, which it's highly likely that you
583 should be using instead. See "libc functions to avoid" above.
584 This includes using Perl IO perlapio.
585 .PP
586 The second thing to know is that Perl is documented to not pay attention
587 to the current locale except for code executed within the scope of a
588 \&\f(CW\*(C`use\ locale\*(C'\fR statement. If you violate that, you may be creating
589 bugs, depending on the application.
590 .PP
591 The next thing to know is that many of these functions depend only on
592 the locale in regards to numeric values. Your code is likely to have
593 been written expecting that the decimal point (radix) character is a dot
594 (U+002E: FULL STOP), and that strings of integer numbers are not
595 separated into groups (1,000,000 in an American locale means a million;
596 your code is likely not expecting the commas.) The good news is that
597 normally (as of Perl v5.22), your code will get called with the locale
598 set so those expectations are met. Explicit action has to be taken to
599 change this (described a little ways below). This is accomplished by
600 Perl not actually switching into a locale that doesn't conform to these
601 expectations, except when explicitly told to do so. The Perl
602 input/output and formatting routines do this switching for you
603 automatically, if appropriate, and then switch back. If, for some
604 reason, you need to do it yourself, the easiest way from C and XS code
605 is to use the macro "\f(CW\*(C`WITH_LC_NUMERIC_SET_TO_NEEDED\*(C'\fR" in perlapi. You
606 can wrap this macro around an entire block of code that you want to be
607 executed in the correct environment. The bottom line is that your code
608 is likely to work as expected in this regard without you having to take
609 any action.
610 .PP
611 This leaves the remaining functions. Your code will get called with all
612 but the numeric locale portions set to the underlying locale. Often,
613 the locale is of not much import to your code, and you also won't have
614 to take any action; things will just work out. But you should examine
615 the man pages of the ones you use to verify this. Often, Perl has
616 better ways of doing the same functionality. Consider using SVs and
617 their access routines rather than calling the low level functions that,
618 for example, find how many bytes are in a UTF\-8 encoded character.
619 .PP
620 You can determine if you have been called from within the scope of a
621 \&\f(CW\*(C`use\ locale\*(C'\fR by using the boolen macro "\f(CW\*(C`IN_LOCALE\*(C'\fR" in perlapi.
622 .PP
623 If you need to not be in the underlying locale, you can call
624 "\f(CW\*(C`Perl_setlocale\*(C'\fR" in perlapi to change it temporarily to the one you
625 need (likely the "C" locale), and then change it back before returning.
626 This can be \fBvery\fR problematic on threaded perls on some platforms. See
627 "Dealing with embedded perls and threads".
628 .PP
629 A problem with changing the locale of a single category is that mojibake
630 can arise on some platforms if the \f(CW\*(C`LC_CTYPE\*(C'\fR category and the changed one
631 are not the same. On the platforms that that isn't an issue, the
632 preprocessor directive \f(CW\*(C`LIBC_HANDLES_MISMATCHED_CTYPE\*(C'\fR will be defined.
633 Otherwise, you may have to change more than one category to correctly
634 accomplish your task. And, there will be many locale combinations where
635 the mojibake likely won't happen, so you won't be confronted with this
636 until the code gets executed in the field by someone who doesn't speak
637 your language very well.
638 .PP
639 Earlier we mentioned that explicit action is required to have your code
640 get called with the numeric portions of the locale not meeting the
641 the typical expectations of having a dot for the radix character and no
642 punctuation separating groups of digits. That action is to call the
643 function "\f(CW\*(C`switch_to_global_locale\*(C'\fR" in perlapi.
644 .PP
645 \&\f(CWswitch_to_global_locale()\fR was written initially to cope with the
646 \&\f(CW\*(C`Tk\*(C'\fR library, but is general enough for other similar situations. \f(CW\*(C`Tk\*(C'\fR
647 changes the global locale to match its expectations (later versions of
648 it allow this to be turned off). This presents a conflict with Perl
649 thinking it also controls the locale. Calling this function tells Perl to
650 yield control. Calling "\f(CW\*(C`sync_locale\*(C'\fR" in perlapi tells Perl to take
651 control again, accepting whatever the locale has been changed to in the
652 interim. If your code is called during that interim, all portions of
653 the locale will be the raw underlying values. Should you need to
654 manipulate numbers, you are on your own with regard to the radix
655 character and grouping. If you find yourself in this situation, it is
656 generally best to make the interval between the calls to these two
657 functions as short as possible, and avoid calculations until after perl
658 has control again.
659 .PP
660 It is important for perl to know about all the possible locale
661 categories on the platform, even if they aren't apparently used in your
662 program. Perl knows all of the Linux ones. If your platform has
663 others, you can submit an issue at
664 <https://github.com/Perl/perl5/issues> for inclusion of it in the next
665 release. In the meantime, it is possible to edit the Perl source to
666 teach it about the category, and then recompile. Search for instances
667 of, say, \f(CW\*(C`LC_PAPER\*(C'\fR in the source, and use that as a template to add
668 the omitted one.
669 .PP
670 There are further complications under multi-threaded operation. Keep on
671 reading.
672 .SH "Dealing with embedded perls and threads"
673 .IX Header "Dealing with embedded perls and threads"
674 It is possible to embed a Perl interpreter within a larger program. See
675 perlembed.
676 .PP
677 MULTIPLICITY is the way this is accomplished internally; it is described in
678 "How multiple interpreters and concurrency are supported" in perlguts.
679 Multiple Perl interpreters may be embedded.
680 .PP
681 It is also possible to compile perl to support threading. See
682 perlthrtut. Perl's implementation of threading requires
683 MULTIPLICITY, but not the other way around.
684 .PP
685 MULTIPLICITY without threading means that only one thing runs at a time,
686 so there are no concurrency issues, but each component or instance can
687 affect the global state, potentially interfering with the execution of
688 other instance. This can happen if one instance:
689 .IP \(bu 4
690 changes the current working directory
691 .IP \(bu 4
692 changes the process's environment
693 .IP \(bu 4
694 changes the global locale the process is operating under
695 .IP \(bu 4
696 writes to shared memory or to a shared file
697 .IP \(bu 4
698 uses a shared file descriptor (including a database iterator)
699 .IP \(bu 4
700 raises a signal that functions in other instances are sensitive to
701 .PP
702 If your code doesn't do any of these things, nor depends on any of their
703 values, then Congratulations!!, you don't have to worry about MULTIPLICITY
704 or threading. But wait, a surprising number of libc functions do
705 depend on data global to the process in some way that may not be
706 immediately obvious. For example, calling \f(CWstrtok(3)\fR changes the
707 global state of a process, and thus needs special attention.
708 .PP
709 The section 3 libc uses that we know about that have MULTIPLICITY and/or
710 multi-thread issues are:
711 .PP
712 .Vb 10
713 \& addmntent() getrpcent_r() re_exec()
714 \& alphasort() getrpcport() regcomp()
715 \& asctime() getservbyname() regerror()
716 \& asctime_r() getservbyname_r() regexec()
717 \& asprintf() getservbyport() res_nclose()
718 \& atof() getservbyport_r() res_ninit()
719 \& atoi() getservent() res_nquery()
720 \& atol() getservent_r() res_nquerydomain()
721 \& atoll() getspent() res_nsearch()
722 \& basename() getspent_r() res_nsend()
723 \& btowc() getspnam() rexec()
724 \& catgets() getspnam_r() rexec_af()
725 \& catopen() getttyent() rpmatch()
726 \& clearenv() getttynam() ruserok()
727 \& clearerr_unlocked() getusershell() ruserok_af()
728 \& crypt() getutent() scandir()
729 \& crypt_gensalt() getutid() scanf()
730 \& crypt_r() getutline() secure_getenv()
731 \& ctermid() getutxent() seed48()
732 \& ctermid_r() getutxid() seed48_r()
733 \& ctime() getutxline() setaliasent()
734 \& ctime_r() getwc() setcontext()
735 \& cuserid() getwchar() setenv()
736 \& daylight getwchar_unlocked() setfsent()
737 \& dbm_clearerr() getwc_unlocked() setgrent()
738 \& dbm_close() glob() setgrent_r()
739 \& dbm_delete() gmtime() sethostent()
740 \& dbm_error() gmtime_r() sethostent_r()
741 \& dbm_fetch() grantpt() sethostid()
742 \& dbm_firstkey() hcreate() setkey()
743 \& dbm_nextkey() hcreate_r() setlocale()
744 \& dbm_open() hdestroy() setlocale_r()
745 \& dbm_store() hdestroy_r() setlogmask()
746 \& dirname() hsearch() setnetent()
747 \& dlerror() hsearch_r() setnetent_r()
748 \& dprintf() iconv() setnetgrent()
749 \& drand48() iconv_open() setprotoent()
750 \& drand48_r() inet_addr() setprotoent_r()
751 \& ecvt() inet_aton() setpwent()
752 \& encrypt() inet_network() setpwent_r()
753 \& endaliasent() inet_ntoa() setrpcent()
754 \& endfsent() inet_ntop() setservent()
755 \& endgrent() inet_pton() setservent_r()
756 \& endgrent_r() initgroups() setspent()
757 \& endhostent() initstate_r() setstate_r()
758 \& endhostent_r() innetgr() setttyent()
759 \& endnetent() iruserok() setusershell()
760 \& endnetent_r() iruserok_af() setutent()
761 \& endnetgrent() isalnum() setutxent()
762 \& endprotoent() isalnum_l() sgetspent()
763 \& endprotoent_r() isalpha() sgetspent_r()
764 \& endpwent() isalpha_l() shm_open()
765 \& endpwent_r() isascii() shm_unlink()
766 \& endrpcent() isascii_l() siginterrupt()
767 \& endservent() isblank() sleep()
768 \& endservent_r() isblank_l() snprintf()
769 \& endspent() iscntrl() sprintf()
770 \& endttyent() iscntrl_l() srand48()
771 \& endusershell() isdigit() srand48_r()
772 \& endutent() isdigit_l() srandom_r()
773 \& endutxent() isgraph() sscanf()
774 \& erand48() isgraph_l() ssignal()
775 \& erand48_r() islower() strcasecmp()
776 \& err() islower_l() strcasestr()
777 \& error() isprint() strcoll()
778 \& error_at_line() isprint_l() strerror()
779 \& errx() ispunct() strerror_l()
780 \& ether_aton() ispunct_l() strerror_r()
781 \& ether_ntoa() isspace() strfmon()
782 \& execlp() isspace_l() strfmon_l()
783 \& execvp() isupper() strfromd()
784 \& execvpe() isupper_l() strfromf()
785 \& exit() iswalnum() strfroml()
786 \& _\|_fbufsize() iswalnum_l() strftime()
787 \& fcloseall() iswalpha() strftime_l()
788 \& fcvt() iswalpha_l() strncasecmp()
789 \& fflush_unlocked() iswblank() strptime()
790 \& fgetc_unlocked() iswblank_l() strsignal()
791 \& fgetgrent() iswcntrl() strtod()
792 \& fgetpwent() iswcntrl_l() strtof()
793 \& fgetspent() iswdigit() strtoimax()
794 \& fgets_unlocked() iswdigit_l() strtok()
795 \& fgetwc() iswgraph() strtol()
796 \& fgetwc_unlocked() iswgraph_l() strtold()
797 \& fgetws() iswlower() strtoll()
798 \& fgetws_unlocked() iswlower_l() strtoq()
799 \& fnmatch() iswprint() strtoul()
800 \& forkpty() iswprint_l() strtoull()
801 \& _\|_fpending() iswpunct() strtoumax()
802 \& fprintf() iswpunct_l() strtouq()
803 \& _\|_fpurge() iswspace() strverscmp()
804 \& fputc_unlocked() iswspace_l() strxfrm()
805 \& fputs_unlocked() iswupper() swapcontext()
806 \& fputwc() iswupper_l() swprintf()
807 \& fputwc_unlocked() iswxdigit() swscanf()
808 \& fputws() iswxdigit_l() sysconf()
809 \& fputws_unlocked() isxdigit() syslog()
810 \& fread_unlocked() isxdigit_l() system()
811 \& fscanf() jrand48() tdelete()
812 \& _\|_fsetlocking() jrand48_r() tempnam()
813 \& fts_children() l64a() tfind()
814 \& fts_read() lcong48() timegm()
815 \& ftw() lcong48_r() timelocal()
816 \& fwprintf() lgamma() timezone
817 \& fwrite_unlocked() lgammaf() tmpnam()
818 \& fwscanf() lgammal() tmpnam_r()
819 \& gamma() localeconv() tolower()
820 \& gammaf() localtime() tolower_l()
821 \& gammal() localtime_r() toupper()
822 \& getaddrinfo() login() toupper_l()
823 \& getaliasbyname() login_tty() towctrans()
824 \& getaliasbyname_r() logout() towlower()
825 \& getaliasent() logwtmp() towlower_l()
826 \& getaliasent_r() lrand48() towupper()
827 \& getchar_unlocked() lrand48_r() towupper_l()
828 \& getcontext() makecontext() tsearch()
829 \& getc_unlocked() mallinfo() ttyname()
830 \& get_current_dir_name() MB_CUR_MAX ttyname_r()
831 \& getdate() mblen() ttyslot()
832 \& getdate_r() mbrlen() twalk()
833 \& getenv() mbrtowc() twalk_r()
834 \& getfsent() mbsinit() tzname
835 \& getfsfile() mbsnrtowcs() tzset()
836 \& getfsspec() mbsrtowcs() ungetwc()
837 \& getgrent() mbstowcs() unsetenv()
838 \& getgrent_r() mbtowc() updwtmp()
839 \& getgrgid() mcheck() utmpname()
840 \& getgrgid_r() mcheck_check_all() va_arg()
841 \& getgrnam() mcheck_pedantic() valloc()
842 \& getgrnam_r() mktime() vasprintf()
843 \& getgrouplist() mprobe() vdprintf()
844 \& gethostbyaddr() mrand48() verr()
845 \& gethostbyaddr_r() mrand48_r() verrx()
846 \& gethostbyname() mtrace() versionsort()
847 \& gethostbyname2() muntrace() vfprintf()
848 \& gethostbyname2_r() nan() vfscanf()
849 \& gethostbyname_r() nanf() vfwprintf()
850 \& gethostent() nanl() vprintf()
851 \& gethostent_r() newlocale() vscanf()
852 \& gethostid() nftw() vsnprintf()
853 \& getlogin() nl_langinfo() vsprintf()
854 \& getlogin_r() nrand48() vsscanf()
855 \& getmntent() nrand48_r() vswprintf()
856 \& getmntent_r() openpty() vsyslog()
857 \& getnameinfo() perror() vwarn()
858 \& getnetbyaddr() posix_fallocate() vwarnx()
859 \& getnetbyaddr_r() printf() vwprintf()
860 \& getnetbyname() profil() warn()
861 \& getnetbyname_r() psiginfo() warnx()
862 \& getnetent() psignal() wcrtomb()
863 \& getnetent_r() ptsname() wcscasecmp()
864 \& getnetgrent() putchar_unlocked() wcschr()
865 \& getnetgrent_r() putc_unlocked() wcscoll()
866 \& getopt() putenv() wcsftime()
867 \& getopt_long() putpwent() wcsncasecmp()
868 \& getopt_long_only() putspent() wcsnrtombs()
869 \& getpass() pututline() wcsrchr()
870 \& getprotobyname() pututxline() wcsrtombs()
871 \& getprotobyname_r() putwc() wcstod()
872 \& getprotobynumber() putwchar() wcstof()
873 \& getprotobynumber_r() putwchar_unlocked() wcstoimax()
874 \& getprotoent() putwc_unlocked() wcstold()
875 \& getprotoent_r() pvalloc() wcstombs()
876 \& getpw() qecvt() wcstoumax()
877 \& getpwent() qfcvt() wcswidth()
878 \& getpwent_r() querylocale() wcsxfrm()
879 \& getpwnam() rand() wctob()
880 \& getpwnam_r() random_r() wctomb()
881 \& getpwuid() rcmd() wctrans()
882 \& getpwuid_r() rcmd_af() wctype()
883 \& getrpcbyname() readdir() wcwidth()
884 \& getrpcbyname_r() readdir64() wordexp()
885 \& getrpcbynumber() readdir64_r() wprintf()
886 \& getrpcbynumber_r() readdir_r() wscanf()
887 \& getrpcent() re_comp() wsetlocale()
888 .Ve
889 .PP
890 (If you know of additional functions that are unsafe on some platform or
891 another, notify us via filing a bug report at
892 <https://github.com/Perl/perl5/issues>.)
893 .PP
894 Some of these are safe under MULTIPLICITY, problematic only under threading.
895 If a use doesn't appear in the above list, we think it is MULTIPLICITY
896 and thread-safe on all platforms.
897 .PP
898 All the uses listed above are function calls, except for these:
899 .PP
900 .Vb 1
901 \& daylight MB_CUR_MAX timezone tzname
902 .Ve
903 .PP
904 There are three main approaches to coping with issues involving these
905 constructs, each suitable for different circumstances:
906 .IP \(bu 4
907 Don't use them. Some of them have preferred alternatives. Use the list
908 above in "libc functions to avoid" to replace your uses with ones
909 that are thread-friendly. For example I/O, should be done via
910 perlapio.
911 .Sp
912 If you must use them, many, but not all, of them will be ok as long as
913 their use is confined to a single thread that has no interaction with
914 conflicting uses in other threads. You will need to closely examine
915 their man pages for this, and be aware that vendor documentation is
916 often imprecise.
917 .IP \(bu 4
918 Do all your business before any other code can change things. If you
919 make changes, change back before returning.
920 .IP \(bu 4
921 Save the result of a query of global information to a per-instance area
922 before allowing another instance to execute. Then you can work on it at
923 your leisure. This might be an automatic C variable for non-pointers,
924 or something as described above in
925 \&\f(CW\*(C`"Safely Storing Static Data in XS" in perlxs\*(C'\fR.
926 .PP
927 Without threading, you don't have to worry about being interrupted by
928 the system giving control to another thread. With threading, you will
929 have to uses mutexes, and be concerned with the possibility of deadlock.
930 .SS "Functions always unsuitable for use under multi-threads"
931 .IX Subsection "Functions always unsuitable for use under multi-threads"
932 A few functions are considered totally unsuited for use in a multi-thread
933 environment. These must be called only during single-thread operation.
934 .PP
935 .Vb 6
936 \& endusershell() @getaliasent() muntrace() rexec()
937 \& ether_aton() @getrpcbyname() profil() rexec_af()
938 \& ether_ntoa() @getrpcbynumber() rcmd() setusershell()
939 \& fts_children() @getrpcent() rcmd_af() ttyslot()
940 \& fts_read() getusershell() re_comp()
941 \& @getaliasbyname() mtrace() re_exec()
942 .Ve
943 .PP
944 \&\f(CW\*(C`@\*(C'\fR above marks the functions for which there are preferred alternatives
945 available on some platforms, and those alternatives may be suitable for
946 multi-thread use.
947 .SS "Functions which must be called at least once before starting threads"
948 .IX Subsection "Functions which must be called at least once before starting threads"
949 Some functions perform initialization on their first call that must be done
950 while still in a single-thread environment, but subsequent calls are
951 thread-safe when executed in a critical section.
952 Therefore, they must be called at least once before switching to
953 multi-threads:
954 .PP
955 .Vb 2
956 \& getutent() getutline() getutxid() mallinfo() valloc()
957 \& getutid() getutxent() getutxline() pvalloc()
958 .Ve
959 .SS "Functions that are thread-safe when called with appropriate arguments"
960 .IX Subsection "Functions that are thread-safe when called with appropriate arguments"
961 Some of the functions are thread-safe if called with arguments that
962 comply with certain (easily met) restrictions. These are:
963 .PP
964 .Vb 3
965 \& ctermid() mbrlen() mbsrtowcs() wcrtomb()
966 \& cuserid() mbrtowc() tmpnam() wcsnrtombs()
967 \& error_at_line() mbsnrtowcs() va_arg() wcsrtombs()
968 .Ve
969 .PP
970 See the man pages of each for details. (For completeness, the list
971 includes functions that you shouldn't be using anyway because of other
972 reasons.)
973 .SS "Functions vulnerable to signals"
974 .IX Subsection "Functions vulnerable to signals"
975 Some functions are vulnerable to asynchronous signals. These are:
976 .PP
977 .Vb 3
978 \& getlogin() getutid() getutxid() login() pututline() updwtmp()
979 \& getlogin_r() getutline() getutxline() logout() pututxline() wordexp()
980 \& getutent() getutxent() glob() logwtmp() sleep()
981 .Ve
982 .PP
983 Some libc's implement '\fBsystem()\fR' thread-safely. But in others, it also
984 has signal issues.
985 .SS "General issues with thread-safety"
986 .IX Subsection "General issues with thread-safety"
987 Some libc functions use and/or modify a global state, such as a database.
988 The libc functions presume that there is only one instance at a time
989 operating on that database. Unpredictable results occur if more than one
990 does, even if the database is not changed. For example, typically there is
991 a global iterator for such a data base and that iterator is maintained by
992 libc, so that each new read from any instance advances it, meaning that no
993 instance will see all the entries. The only way to make these thread-safe
994 is to have an exclusive lock on a mutex from the open call through the
995 close. You are advised to not use such databases from more than one
996 instance at a time.
997 .PP
998 Other examples of functions that use a global state include pseudo-random
999 number generators. Some libc implementations of '\fBrand()\fR', for example, may
1000 share the data across threads; and others may have per-thread data. The
1001 shared ones will have unreproducible results, as the threads will vary in
1002 their timings and interactions. This may be what you want; or it may not
1003 be. (This particular function is a candidate to be removed from the POSIX
1004 Standard because of these issues.)
1005 .PP
1006 Functions that output to a stream also are considered thread-unsafe when
1007 locking is not done. But the typical consequences are just that the data
1008 is output in an unpredictable order; that outcome may be totally
1009 acceptable to you.
1010 .PP
1011 Since the current working directory is global to a process, all
1012 instances depend on it. One instance doing a \fBchdir\fR\|(2) affects all the
1013 other instances. In a multi-threaded environment, any libc call that
1014 expects the directory to not change for the duration of its execution
1015 will have undefined results if another thread interrupts it at just the
1016 wrong time and changes the directory. The man pages only list one such
1017 call, \fBnftw()\fR. But there may be other issues lurking.
1018 .SS "Reentrant equivalent functions"
1019 .IX Subsection "Reentrant equivalent functions"
1020 Some functions that are problematic with regard to MULTIPLICITY have
1021 reentrant versions (on some or all platforms) that are better suited,
1022 with fewer (perhaps no) races when run under threads.
1023 .PP
1024 Some of these reentrant functions that are available on all platforms
1025 should always be used anyway; they are in the lists directly under
1026 "libc functions to avoid".
1027 .PP
1028 Others may not be available on some platforms, or have issues that makes
1029 them undesirable to use even when they are available. Or it may just be
1030 more complicated and tedious to use the reentrant version. For these,
1031 perl has a mechanism for automatically substituting that reentrant
1032 version when available and desirable, while hiding the complications
1033 from your code. This feature is enabled by default for code in the Perl
1034 core and its extensions. To enable it in other XS modules,
1035 .PP
1036 .Vb 1
1037 \& #define PERL_REENTRANT
1038 .Ve
1039 .PP
1040 It is simpler for you to use the unpreferred version in your code, and
1041 rely on this feature to do the better thing, in part because no
1042 substitution is done if the alternative is not available or desirable on
1043 the platform, nor if threads aren't enabled. You just write as if there
1044 weren't threads, and you get the better behavior without having to think
1045 about it.
1046 .PP
1047 On some platforms the safer library functions may fail if the result
1048 buffer is too small (for example the user group databases may be rather
1049 large, and the reentrant functions may have to carry around a full
1050 snapshot of those databases). Perl will start with a small buffer, but
1051 keep retrying and growing the result buffer until the result fits. If
1052 this limitless growing sounds bad for security or memory consumption
1053 reasons you can recompile Perl with \f(CW\*(C`PERL_REENTRANT_MAXSIZE\*(C'\fR #defined
1054 to the maximum number of bytes you will allow.
1055 .PP
1056 Below is a list of the non-reentrant functions and their reentrant
1057 alternatives. This substitution is done even on functions that you
1058 shouldn't be using in the first place. These are marked by a \f(CW\*(C`*\*(C'\fR. You
1059 should instead use the alternate given in the lists directly under
1060 "libc functions to avoid".
1061 .PP
1062 Even so, some of the preferred alternatives are considered obsolete or
1063 otherwise unwise to use on some platforms. These are marked with a '?'.
1064 Also, some alternatives aren't Perl-defined functions and aren't in in
1065 the POSIX Standard, so won't be widely available. These are marked with
1066 \&'~'. (Remember that the automatic substitution only happens when they
1067 are available and desirable, so you can just use the unpreferred
1068 alternative.)
1069 .PP
1070 .Vb 10
1071 \& *asctime() ?asctime_r()
1072 \& crypt() ~crypt_r()
1073 \& ctermid() ~ctermid_r()
1074 \& *ctime() ?ctime_r()
1075 \& endgrent() ?~endgrent_r()
1076 \& endhostent() ?~endhostent_r()
1077 \& endnetent() ?~endnetent_r()
1078 \& endprotoent() ?~endprotoent_r()
1079 \& endpwent() ?~endpwent_r()
1080 \& endservent() ?~endservent_r()
1081 \& getgrent() ~getgrent_r()
1082 \& getgrgid() getgrgid_r()
1083 \& getgrnam() getgrnam_r()
1084 \& gethostbyaddr() ~gethostbyaddr_r()
1085 \& gethostbyname() ~gethostbyname_r()
1086 \& gethostent() ~gethostent_r()
1087 \& getlogin() getlogin_r()
1088 \& getnetbyaddr() ~getnetbyaddr_r()
1089 \& getnetbyname() ~getnetbyname_r()
1090 \& getnetent() ~getnetent_r()
1091 \& getprotobyname() ~getprotobyname_r()
1092 \& getprotobynumber() ~getprotobynumber_r()
1093 \& getprotoent() ~getprotoent_r()
1094 \& getpwent() ~getpwent_r()
1095 \& getpwnam() getpwnam_r()
1096 \& getpwuid() getpwuid_r()
1097 \& getservbyname() ~getservbyname_r()
1098 \& getservbyport() ~getservbyport_r()
1099 \& getservent() ~getservent_r()
1100 \& getspnam() ~getspnam_r()
1101 \& gmtime() gmtime_r()
1102 \& localtime() localtime_r()
1103 \& readdir() ?readdir_r()
1104 \& readdir64() ~readdir64_r()
1105 \& setgrent() ?~setgrent_r()
1106 \& sethostent() ?~sethostent_r()
1107 \& *setlocale() ?~setlocale_r()
1108 \& setnetent() ?~setnetent_r()
1109 \& setprotoent() ?~setprotoent_r()
1110 \& setpwent() ?~setpwent_r()
1111 \& setservent() ?~setservent_r()
1112 \& *strerror() strerror_r()
1113 \& *tmpnam() ~tmpnam_r()
1114 \& ttyname() ttyname_r()
1115 .Ve
1116 .PP
1117 The Perl-furnished items are documented in perlapi.
1118 .PP
1119 The bottom line is:
1120 .ie n .IP "For items marked ""*""" 4
1121 .el .IP "For items marked \f(CW*\fR" 4
1122 .IX Item "For items marked *"
1123 Replace all uses of these with the preferred alternative given in the
1124 lists directly under "libc functions to avoid".
1125 .IP "For the remaining items" 4
1126 .IX Item "For the remaining items"
1127 If you really need to use these functions, you have two choices:
1128 .RS 4
1129 .IP "If you #define PERL_REENTRANT" 4
1130 .IX Item "If you #define PERL_REENTRANT"
1131 Use the function in the first column as-is, and let perl do the work of
1132 substituting the function in the right column if available on the
1133 platform, and it is deemed suitable for use.
1134 .Sp
1135 You should look at the man pages for both versions to find any other
1136 gotchas.
1137 .IP "If you don't enable automatic substitution" 4
1138 .IX Item "If you don't enable automatic substitution"
1139 You should examine the application's code to determine if the column 1
1140 function presents a real problem under threads given the circumstances
1141 it is used in. You can go directly to the column 2 replacement, but
1142 beware of the ones that are marked. Some of those may be nonexistent or
1143 flaky on some platforms.
1144 .RE
1145 .RS 4
1146 .RE
1147 .SS "Functions that need the environment to be constant"
1148 .IX Subsection "Functions that need the environment to be constant"
1149 Since the environment is global to a process, all instances depend on
1150 it. One instance changing the environment affects all the other
1151 instances. Under threads, any libc call that expects the environment to
1152 not change for the duration of its execution will have undefined results
1153 if another thread interrupts it at just the wrong time and changes it.
1154 These are the functions that the man pages list as being sensitive to
1155 that.
1156 .PP
1157 .Vb 10
1158 \& catopen() gethostbyname2() newlocale()
1159 \& ctime() gethostbyname2_r() regerror()
1160 \& ctime_r() gethostbyname_r() secure_getenv()
1161 \& endhostent() gethostent() sethostent()
1162 \& endhostent_r() gethostent_r() sethostent_r()
1163 \& endnetent() gethostid() setlocale()
1164 \& endnetent_r() getnameinfo() setlocale_r()
1165 \& execlp() getnetbyname() setnetent()
1166 \& execvp() getnetent() setnetent_r()
1167 \& execvpe() getopt() strftime()
1168 \& fnmatch() getopt_long() strptime()
1169 \& getaddrinfo() getopt_long_only() sysconf()
1170 \& get_current_dir_name() getrpcport() syslog()
1171 \& getdate() glob() tempnam()
1172 \& getdate_r() gmtime() timegm()
1173 \& getenv() gmtime_r() timelocal()
1174 \& gethostbyaddr() localtime() tzset()
1175 \& gethostbyaddr_r() localtime_r() vsyslog()
1176 \& gethostbyname() mktime()
1177 .Ve
1178 .PP
1179 Many of these functions are problematic under threads for other reasons
1180 as well. See the man pages for any you use.
1181 .PP
1182 Perl defines mutexes \f(CW\*(C`ENV_READ_LOCK\*(C'\fR and \f(CW\*(C`ENV_READ_UNLOCK\*(C'\fR with which
1183 to wrap calls to these functions. You need to consider the possibility
1184 of deadlock. It is expected that a different mechanism will be in place
1185 and preferred for Perl v5.42.
1186 .SS "Locale-specific issues"
1187 .IX Subsection "Locale-specific issues"
1188 C language programs originally had a single locale global to the entire
1189 process. This was later found to be inadequate for many purposes, so later
1190 extensions changed that, first with Windows, and then POSIX 2008. In
1191 Windows, you can change any thread at any time to operate either with a
1192 per-thread locale, or with the global one, using a special new libc
1193 function. In POSIX, the original API operates only on the global
1194 locale, but there is an entirely new API to manipulate either per-thread
1195 locales or the global one. As with Windows (but using the new API), a
1196 thread can be switched at any time to operate on the global locale, or a
1197 per-thread one.
1198 .PP
1199 When one instance changes the global locale, all other instances using
1200 the global locale are affected. Almost all the locale-related functions
1201 in the list directly under "Dealing with embedded perls and threads"
1202 have undefined behavior if another thread interrupts their execution and
1203 changes the locale. Under threads, another thread could do exactly that.
1204 .PP
1205 But, on systems that have per-thread locales, starting with Perl v5.28,
1206 perl uses them after initialization; the global locale is not used
1207 except if XS code has called \f(CWswitch_to_global_locale()\fR. Doing so
1208 affects only the thread that called it. If a maximum of one instance is
1209 using the global locale, no other instances are affected, the locale of
1210 concurrently executing functions in other threads is not changed, and
1211 this becomes a non-issue. The C preprocessor symbol
1212 \&\f(CW\*(C`USE_THREAD_SAFE_LOCALE\*(C'\fR will be defined if per-thread locales are
1213 available and perl has been compiled to use them. The implementation of
1214 per-thread locales on some platforms, like most *BSD\-based ones, is so
1215 buggy that the perl hints files for them deliberately turn off the
1216 possibility of using them.
1217 .PP
1218 The converse is that on systems with only a global locale, having
1219 different threads using different locales is not likely to work well;
1220 and changing the locale is dangerous, often leading to crashes.
1221 .PP
1222 Perl has extensive code to work as well as possible on both types of
1223 systems. You should always use \f(CWPerl_setlocale()\fR to change and query
1224 the locale, as it portably works across the range of possibilities.
1225 .SH "SEE ALSO"
1226 .IX Header "SEE ALSO"
1227 perlapi, perlapio, perlguts, perlxs