| 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 |