This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
POSIX::asctime pod: Note it always returns English
[perl5.git] / ext / POSIX / lib / POSIX.pod
CommitLineData
37120919
AD
1=head1 NAME
2
3POSIX - Perl interface to IEEE Std 1003.1
4
cb1a09d0
AD
5=head1 SYNOPSIS
6
a17b2d91 7 use POSIX ();
cb1a09d0
AD
8 use POSIX qw(setsid);
9 use POSIX qw(:errno_h :fcntl_h);
10
11 printf "EINTR is %d\n", EINTR;
12
13 $sess_id = POSIX::setsid();
14
15 $fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644);
16 # note: that's a filedescriptor, *NOT* a filehandle
17
37120919
AD
18=head1 DESCRIPTION
19
20The POSIX module permits you to access all (or nearly all) the standard
21POSIX 1003.1 identifiers. Many of these identifiers have been given Perl-ish
90b1bb76
MS
22interfaces.
23
37120919
AD
24This document gives a condensed list of the features available in the POSIX
25module. Consult your operating system's manpages for general information on
26most features. Consult L<perlfunc> for functions which are noted as being
dc416353 27identical or almost identical to Perl's builtin functions.
37120919
AD
28
29The first section describes POSIX functions from the 1003.1 specification.
30The second section describes some classes for signal objects, TTY objects,
31and other miscellaneous objects. The remaining sections list various
32constants and macros in an organization which roughly follows IEEE Std
331003.1b-1993.
34
3609ea0d 35=head1 CAVEATS
37120919 36
ea660a4b
AP
37I<Everything is exported by default> (with a handful of exceptions).
38This is an unfortunate backwards compatibility feature and its use is
39B<strongly L<discouraged|perlpolicy/discouraged>>.
40You should either prevent the exporting (by saying S<C<use POSIX ();>>,
41as usual) and then use fully qualified names (e.g. C<POSIX::SEEK_END>),
42or give an explicit import list.
43If you do neither and opt for the default (as in S<C<use POSIX;>>), you
44will import I<hundreds and hundreds> of symbols into your namespace.
45
37120919
AD
46A few functions are not implemented because they are C specific. If you
47attempt to call these, they will print a message telling you that they
41cd218c
KW
48aren't implemented, and suggest using the Perl equivalent, should one
49exist. For example, trying to access the C<setjmp()> call will elicit the
50message "C<setjmp() is C-specific: use eval {} instead>".
37120919
AD
51
52Furthermore, some evil vendors will claim 1003.1 compliance, but in fact
53are not so: they will not pass the PCTS (POSIX Compliance Test Suites).
41cd218c
KW
54For example, one vendor may not define C<EDEADLK>, or the semantics of the
55errno values set by C<open(2)> might not be quite right. Perl does not
37120919
AD
56attempt to verify POSIX compliance. That means you can currently
57successfully say "use POSIX", and then later in your program you find
41cd218c 58that your vendor has been lax and there's no usable C<ICANON> macro after
37120919
AD
59all. This could be construed to be a bug.
60
61=head1 FUNCTIONS
62
63=over 8
64
41cd218c 65=item C<_exit>
37120919 66
4755096e
GS
67This is identical to the C function C<_exit()>. It exits the program
68immediately which means among other things buffered I/O is B<not> flushed.
37120919 69
15978375
JH
70Note that when using threads and in Linux this is B<not> a good way to
71exit a thread because in Linux processes and threads are kind of the
72same thing (Note: while this is the situation in early 2003 there are
73projects under way to have threads with more POSIXly semantics in Linux).
74If you want not to return from a thread, detach the thread.
75
41cd218c 76=item C<abort>
37120919 77
4755096e
GS
78This is identical to the C function C<abort()>. It terminates the
79process with a C<SIGABRT> signal unless caught by a signal handler or
80if the handler does not return normally (it e.g. does a C<longjmp>).
37120919 81
41cd218c 82=item C<abs>
37120919 83
bda53d3e
JK
84This is identical to Perl's builtin C<abs()> function, returning the absolute
85value of its numerical argument (except that C<POSIX::abs()> must be provided
86an explicit value (rather than relying on an implicit C<$_>):
87
88 $absolute_value = POSIX::abs(42); # good
89
90 $absolute_value = POSIX::abs(); # throws exception
37120919 91
41cd218c 92=item C<access>
37120919
AD
93
94Determines the accessibility of a file.
95
96 if( POSIX::access( "/", &POSIX::R_OK ) ){
97 print "have read permission\n";
98 }
99
4755096e
GS
100Returns C<undef> on failure. Note: do not use C<access()> for
101security purposes. Between the C<access()> call and the operation
102you are preparing for the permissions might change: a classic
103I<race condition>.
37120919 104
41cd218c 105=item C<acos>
37120919 106
4755096e 107This is identical to the C function C<acos()>, returning
c2e66d9e 108the arcus cosine of its numerical argument. See also L<Math::Trig>.
37120919 109
9d233e12
JH
110=item C<acosh>
111
4d0de388 112This is identical to the C function C<acosh()>, returning the
9d233e12 113hyperbolic arcus cosine of its numerical argument [C99]. See also
912a1e06 114L<Math::Trig>. Added in Perl v5.22.
9d233e12 115
41cd218c 116=item C<alarm>
37120919 117
bda53d3e
JK
118This is identical to Perl's builtin C<alarm()> function, either for arming or
119disarming the C<SIGARLM> timer, except that C<POSIX::alarm()> must be provided
120an explicit value (rather than relying on an implicit C<$_>):
121
122 POSIX::alarm(3) # good
123
124 POSIX::alarm() # throws exception
37120919 125
41cd218c 126=item C<asctime>
37120919 127
4755096e
GS
128This is identical to the C function C<asctime()>. It returns
129a string of the form
130
131 "Fri Jun 2 18:22:13 2000\n\0"
132
133and it is called thusly
134
b70c169c
FC
135 $asctime = asctime($sec, $min, $hour, $mday, $mon,
136 $year, $wday, $yday, $isdst);
4755096e
GS
137
138The C<$mon> is zero-based: January equals C<0>. The C<$year> is
c1646883
RGS
1391900-based: 2001 equals C<101>. C<$wday> and C<$yday> default to zero
140(and are usually ignored anyway), and C<$isdst> defaults to -1.
37120919 141
ff22dd70
KW
142Note the result is always in English. Use C<L</strftime>> instead to
143get a result suitable for the current locale. That function's C<%c>
144format yields the locale's preferred representation.
145
41cd218c 146=item C<asin>
37120919 147
4755096e 148This is identical to the C function C<asin()>, returning
c2e66d9e 149the arcus sine of its numerical argument. See also L<Math::Trig>.
37120919 150
9d233e12
JH
151=item C<asinh>
152
4d0de388 153This is identical to the C function C<asinh()>, returning the
9d233e12 154hyperbolic arcus sine of its numerical argument [C99]. See also
912a1e06 155L<Math::Trig>. Added in Perl v5.22.
9d233e12 156
41cd218c 157=item C<assert>
37120919 158
4755096e
GS
159Unimplemented, but you can use L<perlfunc/die> and the L<Carp> module
160to achieve similar things.
37120919 161
41cd218c 162=item C<atan>
37120919 163
4755096e 164This is identical to the C function C<atan()>, returning the
c2e66d9e 165arcus tangent of its numerical argument. See also L<Math::Trig>.
37120919 166
9d233e12
JH
167=item C<atanh>
168
4d0de388 169This is identical to the C function C<atanh()>, returning the
9d233e12 170hyperbolic arcus tangent of its numerical argument [C99]. See also
912a1e06 171L<Math::Trig>. Added in Perl v5.22.
9d233e12 172
41cd218c 173=item C<atan2>
37120919 174
4755096e
GS
175This is identical to Perl's builtin C<atan2()> function, returning
176the arcus tangent defined by its two numerical arguments, the I<y>
c2e66d9e 177coordinate and the I<x> coordinate. See also L<Math::Trig>.
37120919 178
41cd218c 179=item C<atexit>
37120919 180
4d0de388 181Not implemented. C<atexit()> is C-specific: use C<END {}> instead, see L<perlmod>.
37120919 182
41cd218c 183=item C<atof>
37120919 184
4d0de388 185Not implemented. C<atof()> is C-specific. Perl converts strings to numbers transparently.
4755096e 186If you need to force a scalar to a number, add a zero to it.
37120919 187
41cd218c 188=item C<atoi>
37120919 189
4d0de388 190Not implemented. C<atoi()> is C-specific. Perl converts strings to numbers transparently.
4755096e
GS
191If you need to force a scalar to a number, add a zero to it.
192If you need to have just the integer part, see L<perlfunc/int>.
37120919 193
41cd218c 194=item C<atol>
37120919 195
4d0de388 196Not implemented. C<atol()> is C-specific. Perl converts strings to numbers transparently.
4755096e
GS
197If you need to force a scalar to a number, add a zero to it.
198If you need to have just the integer part, see L<perlfunc/int>.
37120919 199
41cd218c 200=item C<bsearch>
37120919 201
41cd218c 202C<bsearch()> not supplied. For doing binary search on wordlists,
4755096e 203see L<Search::Dict>.
37120919 204
41cd218c 205=item C<calloc>
37120919 206
4d0de388 207Not implemented. C<calloc()> is C-specific. Perl does memory management transparently.
37120919 208
9d233e12
JH
209=item C<cbrt>
210
912a1e06 211The cube root [C99]. Added in Perl v5.22.
9d233e12 212
41cd218c 213=item C<ceil>
37120919 214
4755096e
GS
215This is identical to the C function C<ceil()>, returning the smallest
216integer value greater than or equal to the given numerical argument.
37120919 217
41cd218c 218=item C<chdir>
37120919 219
bda53d3e
JK
220This is identical to Perl's builtin C<chdir()> function, allowing one to
221change the working (default) directory -- see L<perlfunc/chdir> -- with the
222exception that C<POSIX::chdir()> must be provided an explicit value (rather
223than relying on an implicit C<$_>):
224
225 $rv = POSIX::chdir('path/to/dir'); # good
226
227 $rv = POSIX::chdir(); # throws exception
37120919 228
41cd218c 229=item C<chmod>
37120919 230
4755096e 231This is identical to Perl's builtin C<chmod()> function, allowing
bda53d3e
JK
232one to change file and directory permissions -- see L<perlfunc/chmod> -- with
233the exception that C<POSIX::chmod()> can only change one file at a time
234(rather than a list of files):
235
236 $c = chmod 0664, $file1, $file2; # good
237
238 $c = POSIX::chmod 0664, $file1; # throws exception
239
240 $c = POSIX::chmod 0664, $file1, $file2; # throws exception
37120919 241
c6f0b8ca
TC
242As with the built-in C<chmod()>, C<$file> may be a filename or a file
243handle.
244
41cd218c 245=item C<chown>
37120919 246
4755096e
GS
247This is identical to Perl's builtin C<chown()> function, allowing one
248to change file and directory owners and groups, see L<perlfunc/chown>.
37120919 249
41cd218c 250=item C<clearerr>
37120919 251
4d0de388 252Not implemented. Use the method C<IO::Handle::clearerr()> instead, to reset the error
4755096e 253state (if any) and EOF state (if any) of the given stream.
37120919 254
41cd218c 255=item C<clock>
37120919 256
4755096e
GS
257This is identical to the C function C<clock()>, returning the
258amount of spent processor time in microseconds.
37120919 259
41cd218c 260=item C<close>
37120919 261
cb1a09d0
AD
262Close the file. This uses file descriptors such as those obtained by calling
263C<POSIX::open>.
264
265 $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
266 POSIX::close( $fd );
37120919
AD
267
268Returns C<undef> on failure.
269
4755096e
GS
270See also L<perlfunc/close>.
271
41cd218c 272=item C<closedir>
37120919 273
4755096e
GS
274This is identical to Perl's builtin C<closedir()> function for closing
275a directory handle, see L<perlfunc/closedir>.
37120919 276
41cd218c 277=item C<cos>
37120919 278
4755096e
GS
279This is identical to Perl's builtin C<cos()> function, for returning
280the cosine of its numerical argument, see L<perlfunc/cos>.
c2e66d9e 281See also L<Math::Trig>.
37120919 282
41cd218c 283=item C<cosh>
37120919 284
4755096e 285This is identical to the C function C<cosh()>, for returning
c2e66d9e 286the hyperbolic cosine of its numeric argument. See also L<Math::Trig>.
37120919 287
9d233e12
JH
288=item C<copysign>
289
912a1e06 290Returns C<x> but with the sign of C<y> [C99]. Added in Perl v5.22.
4d0de388
KW
291
292 $x_with_sign_of_y = POSIX::copysign($x, $y);
9d233e12
JH
293
294See also L</signbit>.
295
41cd218c 296=item C<creat>
37120919 297
cb1a09d0
AD
298Create a new file. This returns a file descriptor like the ones returned by
299C<POSIX::open>. Use C<POSIX::close> to close the file.
300
301 $fd = POSIX::creat( "foo", 0611 );
302 POSIX::close( $fd );
37120919 303
4755096e
GS
304See also L<perlfunc/sysopen> and its C<O_CREAT> flag.
305
41cd218c 306=item C<ctermid>
37120919 307
cb1a09d0 308Generates the path name for the controlling terminal.
37120919
AD
309
310 $path = POSIX::ctermid();
311
41cd218c 312=item C<ctime>
37120919 313
4755096e
GS
314This is identical to the C function C<ctime()> and equivalent
315to C<asctime(localtime(...))>, see L</asctime> and L</localtime>.
37120919 316
631637d8 317=item C<cuserid> [POSIX.1-1988]
37120919 318
4755096e 319Get the login name of the owner of the current process.
37120919
AD
320
321 $name = POSIX::cuserid();
322
631637d8
MB
323Note: this function has not been specified by POSIX since 1990 and is included
324only for backwards compatibility. New code should use L<C<getlogin()>|perlfunc/getlogin> instead.
325
41cd218c 326=item C<difftime>
37120919 327
4755096e
GS
328This is identical to the C function C<difftime()>, for returning
329the time difference (in seconds) between two times (as returned
330by C<time()>), see L</time>.
37120919 331
41cd218c 332=item C<div>
37120919 333
4d0de388 334Not implemented. C<div()> is C-specific, use L<perlfunc/int> on the usual C</> division and
4755096e 335the modulus C<%>.
37120919 336
41cd218c 337=item C<dup>
37120919 338
4755096e
GS
339This is similar to the C function C<dup()>, for duplicating a file
340descriptor.
cb1a09d0
AD
341
342This uses file descriptors such as those obtained by calling
343C<POSIX::open>.
37120919
AD
344
345Returns C<undef> on failure.
346
41cd218c 347=item C<dup2>
37120919 348
4755096e
GS
349This is similar to the C function C<dup2()>, for duplicating a file
350descriptor to an another known file descriptor.
cb1a09d0
AD
351
352This uses file descriptors such as those obtained by calling
353C<POSIX::open>.
37120919
AD
354
355Returns C<undef> on failure.
356
9d233e12
JH
357=item C<erf>
358
912a1e06 359The error function [C99]. Added in Perl v5.22.
9d233e12
JH
360
361=item C<erfc>
362
912a1e06 363The complementary error function [C99]. Added in Perl v5.22.
9d233e12 364
41cd218c 365=item C<errno>
37120919
AD
366
367Returns the value of errno.
368
369 $errno = POSIX::errno();
370
4755096e
GS
371This identical to the numerical values of the C<$!>, see L<perlvar/$ERRNO>.
372
41cd218c 373=item C<execl>
37120919 374
4d0de388 375Not implemented. C<execl()> is C-specific, see L<perlfunc/exec>.
37120919 376
41cd218c 377=item C<execle>
37120919 378
4d0de388 379Not implemented. C<execle()> is C-specific, see L<perlfunc/exec>.
37120919 380
41cd218c 381=item C<execlp>
37120919 382
4d0de388 383Not implemented. C<execlp()> is C-specific, see L<perlfunc/exec>.
37120919 384
41cd218c 385=item C<execv>
37120919 386
4d0de388 387Not implemented. C<execv()> is C-specific, see L<perlfunc/exec>.
37120919 388
41cd218c 389=item C<execve>
37120919 390
4d0de388 391Not implemented. C<execve()> is C-specific, see L<perlfunc/exec>.
37120919 392
41cd218c 393=item C<execvp>
37120919 394
4d0de388 395Not implemented. C<execvp()> is C-specific, see L<perlfunc/exec>.
37120919 396
41cd218c 397=item C<exit>
37120919 398
4755096e
GS
399This is identical to Perl's builtin C<exit()> function for exiting the
400program, see L<perlfunc/exit>.
37120919 401
41cd218c 402=item C<exp>
37120919 403
4755096e
GS
404This is identical to Perl's builtin C<exp()> function for
405returning the exponent (I<e>-based) of the numerical argument,
406see L<perlfunc/exp>.
37120919 407
9d233e12
JH
408=item C<expm1>
409
410Equivalent to C<exp(x) - 1>, but more precise for small argument values [C99].
912a1e06 411Added in Perl v5.22.
9d233e12
JH
412
413See also L</log1p>.
414
41cd218c 415=item C<fabs>
37120919 416
4755096e
GS
417This is identical to Perl's builtin C<abs()> function for returning
418the absolute value of the numerical argument, see L<perlfunc/abs>.
37120919 419
41cd218c 420=item C<fclose>
37120919 421
4d0de388 422Not implemented. Use method C<IO::Handle::close()> instead, or see L<perlfunc/close>.
37120919 423
41cd218c 424=item C<fcntl>
37120919 425
4755096e
GS
426This is identical to Perl's builtin C<fcntl()> function,
427see L<perlfunc/fcntl>.
37120919 428
41cd218c 429=item C<fdopen>
37120919 430
4d0de388 431Not implemented. Use method C<IO::Handle::new_from_fd()> instead, or see L<perlfunc/open>.
37120919 432
41cd218c 433=item C<feof>
37120919 434
4d0de388 435Not implemented. Use method C<IO::Handle::eof()> instead, or see L<perlfunc/eof>.
37120919 436
41cd218c 437=item C<ferror>
37120919 438
4d0de388 439Not implemented. Use method C<IO::Handle::error()> instead.
37120919 440
41cd218c 441=item C<fflush>
37120919 442
4d0de388 443Not implemented. Use method C<IO::Handle::flush()> instead.
41cd218c 444See also C<L<perlvar/$OUTPUT_AUTOFLUSH>>.
37120919 445
41cd218c 446=item C<fgetc>
37120919 447
4d0de388 448Not implemented. Use method C<IO::Handle::getc()> instead, or see L<perlfunc/read>.
37120919 449
41cd218c 450=item C<fgetpos>
37120919 451
4d0de388 452Not implemented. Use method C<IO::Seekable::getpos()> instead, or see L<perlfunc/seek>.
37120919 453
41cd218c 454=item C<fgets>
37120919 455
4d0de388 456Not implemented. Use method C<IO::Handle::gets()> instead. Similar to E<lt>E<gt>, also known
4755096e 457as L<perlfunc/readline>.
37120919 458
41cd218c 459=item C<fileno>
37120919 460
4d0de388 461Not implemented. Use method C<IO::Handle::fileno()> instead, or see L<perlfunc/fileno>.
37120919 462
41cd218c 463=item C<floor>
37120919 464
4755096e
GS
465This is identical to the C function C<floor()>, returning the largest
466integer value less than or equal to the numerical argument.
37120919 467
9d233e12
JH
468=item C<fdim>
469
4d0de388 470"Positive difference", S<C<x - y>> if S<C<x E<gt> y>>, zero otherwise [C99].
912a1e06 471Added in Perl v5.22.
9d233e12
JH
472
473=item C<fegetround>
474
475Returns the current floating point rounding mode, one of
476
387e2cd4 477 FE_TONEAREST FE_TOWARDZERO FE_UPWARD FE_DOWNWARD
9d233e12 478
4d0de388 479C<FE_TONEAREST> is like L</round>, C<FE_TOWARDZERO> is like L</trunc> [C99].
912a1e06 480Added in Perl v5.22.
9d233e12
JH
481
482=item C<fesetround>
483
912a1e06
DB
484Sets the floating point rounding mode, see L</fegetround> [C99]. Added in
485Perl v5.22.
9d233e12
JH
486
487=item C<fma>
488
4d0de388 489"Fused multiply-add", S<C<x * y + z>>, possibly faster (and less lossy)
912a1e06 490than the explicit two operations [C99]. Added in Perl v5.22.
9d233e12 491
4d0de388
KW
492 my $fused = POSIX::fma($x, $y, $z);
493
9d233e12
JH
494=item C<fmax>
495
4d0de388 496Maximum of C<x> and C<y>, except when either is C<NaN>, returns the other [C99].
912a1e06 497Added in Perl v5.22.
4d0de388
KW
498
499 my $min = POSIX::fmax($x, $y);
9d233e12
JH
500
501=item C<fmin>
502
4d0de388 503Minimum of C<x> and C<y>, except when either is C<NaN>, returns the other [C99].
912a1e06 504Added in Perl v5.22.
4d0de388
KW
505
506 my $min = POSIX::fmin($x, $y);
9d233e12 507
41cd218c 508=item C<fmod>
37120919
AD
509
510This is identical to the C function C<fmod()>.
511
847f7ebc 512 $r = fmod($x, $y);
4755096e 513
4d0de388 514It returns the remainder S<C<$r = $x - $n*$y>>, where S<C<$n = trunc($x/$y)>>.
4755096e
GS
515The C<$r> has the same sign as C<$x> and magnitude (absolute value)
516less than the magnitude of C<$y>.
517
41cd218c 518=item C<fopen>
37120919 519
4d0de388 520Not implemented. Use method C<IO::File::open()> instead, or see L<perlfunc/open>.
37120919 521
41cd218c 522=item C<fork>
37120919 523
c2e66d9e
GS
524This is identical to Perl's builtin C<fork()> function
525for duplicating the current process, see L<perlfunc/fork>
526and L<perlfork> if you are in Windows.
37120919 527
41cd218c 528=item C<fpathconf>
37120919 529
cb1a09d0
AD
530Retrieves the value of a configurable limit on a file or directory. This
531uses file descriptors such as those obtained by calling C<POSIX::open>.
532
533The following will determine the maximum length of the longest allowable
f703fc96 534pathname on the filesystem which holds F</var/foo>.
cb1a09d0 535
2359510d 536 $fd = POSIX::open( "/var/foo", &POSIX::O_RDONLY );
b70c169c 537 $path_max = POSIX::fpathconf($fd, &POSIX::_PC_PATH_MAX);
37120919
AD
538
539Returns C<undef> on failure.
540
9d233e12
JH
541=item C<fpclassify>
542
543Returns one of
544
545 FP_NORMAL FP_ZERO FP_SUBNORMAL FP_INFINITE FP_NAN
546
d7a0f0b0
JH
547telling the class of the argument [C99]. C<FP_INFINITE> is positive
548or negative infinity, C<FP_NAN> is not-a-number. C<FP_SUBNORMAL>
549means subnormal numbers (also known as denormals), very small numbers
550with low precision. C<FP_ZERO> is zero. C<FP_NORMAL> is all the rest.
912a1e06 551Added in Perl v5.22.
9d233e12 552
41cd218c 553=item C<fprintf>
37120919 554
4d0de388 555Not implemented. C<fprintf()> is C-specific, see L<perlfunc/printf> instead.
37120919 556
41cd218c 557=item C<fputc>
37120919 558
4d0de388 559Not implemented. C<fputc()> is C-specific, see L<perlfunc/print> instead.
37120919 560
41cd218c 561=item C<fputs>
37120919 562
4d0de388 563Not implemented. C<fputs()> is C-specific, see L<perlfunc/print> instead.
37120919 564
41cd218c 565=item C<fread>
37120919 566
4d0de388 567Not implemented. C<fread()> is C-specific, see L<perlfunc/read> instead.
37120919 568
41cd218c 569=item C<free>
37120919 570
4d0de388 571Not implemented. C<free()> is C-specific. Perl does memory management transparently.
37120919 572
41cd218c 573=item C<freopen>
37120919 574
4d0de388 575Not implemented. C<freopen()> is C-specific, see L<perlfunc/open> instead.
37120919 576
41cd218c 577=item C<frexp>
37120919 578
cb1a09d0
AD
579Return the mantissa and exponent of a floating-point number.
580
4755096e 581 ($mantissa, $exponent) = POSIX::frexp( 1.234e56 );
37120919 582
41cd218c 583=item C<fscanf>
37120919 584
4d0de388 585Not implemented. C<fscanf()> is C-specific, use E<lt>E<gt> and regular expressions instead.
37120919 586
41cd218c 587=item C<fseek>
37120919 588
4d0de388 589Not implemented. Use method C<IO::Seekable::seek()> instead, or see L<perlfunc/seek>.
37120919 590
41cd218c 591=item C<fsetpos>
37120919 592
4d0de388 593Not implemented. Use method C<IO::Seekable::setpos()> instead, or seek L<perlfunc/seek>.
37120919 594
41cd218c 595=item C<fstat>
37120919 596
cb1a09d0
AD
597Get file status. This uses file descriptors such as those obtained by
598calling C<POSIX::open>. The data returned is identical to the data from
599Perl's builtin C<stat> function.
600
601 $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
602 @stats = POSIX::fstat( $fd );
37120919 603
41cd218c 604=item C<fsync>
f0709b24 605
4d0de388 606Not implemented. Use method C<IO::Handle::sync()> instead.
f0709b24 607
41cd218c 608=item C<ftell>
37120919 609
4d0de388 610Not implemented. Use method C<IO::Seekable::tell()> instead, or see L<perlfunc/tell>.
37120919 611
41cd218c 612=item C<fwrite>
37120919 613
4d0de388 614Not implemented. C<fwrite()> is C-specific, see L<perlfunc/print> instead.
37120919 615
41cd218c 616=item C<getc>
37120919 617
4755096e
GS
618This is identical to Perl's builtin C<getc()> function,
619see L<perlfunc/getc>.
37120919 620
41cd218c 621=item C<getchar>
37120919 622
4755096e
GS
623Returns one character from STDIN. Identical to Perl's C<getc()>,
624see L<perlfunc/getc>.
37120919 625
41cd218c 626=item C<getcwd>
37120919
AD
627
628Returns the name of the current working directory.
4755096e 629See also L<Cwd>.
37120919 630
41cd218c 631=item C<getegid>
37120919 632
4755096e
GS
633Returns the effective group identifier. Similar to Perl' s builtin
634variable C<$(>, see L<perlvar/$EGID>.
37120919 635
41cd218c 636=item C<getenv>
37120919 637
d7f8936a 638Returns the value of the specified environment variable.
4755096e 639The same information is available through the C<%ENV> array.
37120919 640
41cd218c 641=item C<geteuid>
37120919 642
4755096e
GS
643Returns the effective user identifier. Identical to Perl's builtin C<$E<gt>>
644variable, see L<perlvar/$EUID>.
37120919 645
41cd218c 646=item C<getgid>
37120919 647
4755096e
GS
648Returns the user's real group identifier. Similar to Perl's builtin
649variable C<$)>, see L<perlvar/$GID>.
37120919 650
41cd218c 651=item C<getgrgid>
37120919 652
4755096e
GS
653This is identical to Perl's builtin C<getgrgid()> function for
654returning group entries by group identifiers, see
655L<perlfunc/getgrgid>.
37120919 656
41cd218c 657=item C<getgrnam>
37120919 658
4755096e
GS
659This is identical to Perl's builtin C<getgrnam()> function for
660returning group entries by group names, see L<perlfunc/getgrnam>.
37120919 661
41cd218c 662=item C<getgroups>
37120919 663
4755096e
GS
664Returns the ids of the user's supplementary groups. Similar to Perl's
665builtin variable C<$)>, see L<perlvar/$GID>.
37120919 666
41cd218c 667=item C<getlogin>
37120919 668
4755096e
GS
669This is identical to Perl's builtin C<getlogin()> function for
670returning the user name associated with the current session, see
671L<perlfunc/getlogin>.
37120919 672
07bb61ac
JH
673=item C<getpayload>
674
675 use POSIX ':nan_payload';
676 getpayload($var)
677
912a1e06 678Returns the C<NaN> payload. Added in Perl v5.24.
07bb61ac
JH
679
680Note the API instability warning in L</setpayload>.
681
682See L</nan> for more discussion about C<NaN>.
683
41cd218c 684=item C<getpgrp>
37120919 685
4755096e 686This is identical to Perl's builtin C<getpgrp()> function for
d7f8936a 687returning the process group identifier of the current process, see
4755096e 688L<perlfunc/getpgrp>.
37120919 689
41cd218c 690=item C<getpid>
37120919 691
4755096e
GS
692Returns the process identifier. Identical to Perl's builtin
693variable C<$$>, see L<perlvar/$PID>.
37120919 694
41cd218c 695=item C<getppid>
37120919 696
4755096e
GS
697This is identical to Perl's builtin C<getppid()> function for
698returning the process identifier of the parent process of the current
699process , see L<perlfunc/getppid>.
37120919 700
41cd218c 701=item C<getpwnam>
37120919 702
4755096e
GS
703This is identical to Perl's builtin C<getpwnam()> function for
704returning user entries by user names, see L<perlfunc/getpwnam>.
37120919 705
41cd218c 706=item C<getpwuid>
37120919 707
4755096e
GS
708This is identical to Perl's builtin C<getpwuid()> function for
709returning user entries by user identifiers, see L<perlfunc/getpwuid>.
37120919 710
41cd218c 711=item C<gets>
37120919 712
4755096e
GS
713Returns one line from C<STDIN>, similar to E<lt>E<gt>, also known
714as the C<readline()> function, see L<perlfunc/readline>.
715
716B<NOTE>: if you have C programs that still use C<gets()>, be very
717afraid. The C<gets()> function is a source of endless grief because
718it has no buffer overrun checks. It should B<never> be used. The
719C<fgets()> function should be preferred instead.
37120919 720
41cd218c 721=item C<getuid>
37120919 722
4755096e
GS
723Returns the user's identifier. Identical to Perl's builtin C<$E<lt>> variable,
724see L<perlvar/$UID>.
37120919 725
41cd218c 726=item C<gmtime>
37120919 727
4755096e
GS
728This is identical to Perl's builtin C<gmtime()> function for
729converting seconds since the epoch to a date in Greenwich Mean Time,
730see L<perlfunc/gmtime>.
37120919 731
9d233e12
JH
732=item C<hypot>
733
4d0de388 734Equivalent to C<S<sqrt(x * x + y * y)>> except more stable on very large
912a1e06 735or very small arguments [C99]. Added in Perl v5.22.
9d233e12
JH
736
737=item C<ilogb>
738
912a1e06 739Integer binary logarithm [C99]. Added in Perl v5.22.
9d233e12 740
4d0de388 741For example C<ilogb(20)> is 4, as an integer.
351ab2ad
JH
742
743See also L</logb>.
9d233e12 744
d7a0f0b0
JH
745=item C<Inf>
746
747The infinity as a constant:
748
749 use POSIX qw(Inf);
750 my $pos_inf = +Inf; # Or just Inf.
751 my $neg_inf = -Inf;
752
753See also L</isinf>, and L</fpclassify>.
754
41cd218c 755=item C<isalnum>
37120919 756
912a1e06 757This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
758matching against S<C<qr/ ^ [[:alnum:]]+ $ /x>>, which you should convert
759to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 760
41cd218c 761=item C<isalpha>
37120919 762
912a1e06 763This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
764matching against S<C<qr/ ^ [[:alpha:]]+ $ /x>>, which you should convert
765to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 766
41cd218c 767=item C<isatty>
37120919
AD
768
769Returns a boolean indicating whether the specified filehandle is connected
4755096e 770to a tty. Similar to the C<-t> operator, see L<perlfunc/-X>.
37120919 771
41cd218c 772=item C<iscntrl>
37120919 773
912a1e06 774This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
775matching against S<C<qr/ ^ [[:cntrl:]]+ $ /x>>, which you should convert
776to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 777
41cd218c 778=item C<isdigit>
37120919 779
912a1e06 780This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
781matching against S<C<qr/ ^ [[:digit:]]+ $ /x>>, which you should convert
782to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 783
9d233e12
JH
784=item C<isfinite>
785
786Returns true if the argument is a finite number (that is, not an
912a1e06 787infinity, or the not-a-number) [C99]. Added in Perl v5.22.
9d233e12 788
3823048b 789See also L</isinf>, L</isnan>, and L</fpclassify>.
9d233e12 790
41cd218c 791=item C<isgraph>
37120919 792
912a1e06 793This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
794matching against S<C<qr/ ^ [[:graph:]]+ $ /x>>, which you should convert
795to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 796
9d233e12
JH
797=item C<isgreater>
798
799(Also C<isgreaterequal>, C<isless>, C<islessequal>, C<islessgreater>,
800C<isunordered>)
801
912a1e06
DB
802Floating point comparisons which handle the C<NaN> [C99]. Added in Perl
803v5.22.
9d233e12
JH
804
805=item C<isinf>
806
807Returns true if the argument is an infinity (positive or negative) [C99].
912a1e06 808Added in Perl v5.22.
9d233e12 809
d7a0f0b0 810See also L</Inf>, L</isnan>, L</isfinite>, and L</fpclassify>.
9d233e12 811
41cd218c 812=item C<islower>
37120919 813
912a1e06 814This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
815matching against S<C<qr/ ^ [[:lower:]]+ $ /x>>, which you should convert
816to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 817
9d233e12
JH
818=item C<isnan>
819
912a1e06
DB
820Returns true if the argument is C<NaN> (not-a-number) [C99]. Added in
821Perl v5.22.
9d233e12 822
4d0de388 823Note that you cannot test for "C<NaN>-ness" with
9d233e12
JH
824
825 $x == $x
826
4d0de388 827since the C<NaN> is not equivalent to anything, B<including itself>.
9d233e12 828
d7a0f0b0 829See also L</nan>, L</NaN>, L</isinf>, and L</fpclassify>.
9d233e12
JH
830
831=item C<isnormal>
832
833Returns true if the argument is normal (that is, not a subnormal/denormal,
912a1e06 834and not an infinity, or a not-a-number) [C99]. Added in Perl v5.22.
9d233e12
JH
835
836See also L</isfinite>, and L</fpclassify>.
837
41cd218c 838=item C<isprint>
37120919 839
912a1e06 840This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
841matching against S<C<qr/ ^ [[:print:]]+ $ /x>>, which you should convert
842to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 843
41cd218c 844=item C<ispunct>
37120919 845
912a1e06 846This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
847matching against S<C<qr/ ^ [[:punct:]]+ $ /x>>, which you should convert
848to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 849
07bb61ac
JH
850=item C<issignaling>
851
852 use POSIX ':nan_payload';
853 issignaling($var, $payload)
854
912a1e06 855Return true if the argument is a I<signaling> NaN. Added in Perl v5.24.
07bb61ac
JH
856
857Note the API instability warning in L</setpayload>.
858
859See L</nan> for more discussion about C<NaN>.
860
41cd218c 861=item C<isspace>
37120919 862
912a1e06 863This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
864matching against S<C<qr/ ^ [[:space:]]+ $ /x>>, which you should convert
865to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 866
41cd218c 867=item C<isupper>
37120919 868
912a1e06 869This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
870matching against S<C<qr/ ^ [[:upper:]]+ $ /x>>, which you should convert
871to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 872
41cd218c 873=item C<isxdigit>
37120919 874
912a1e06 875This function has been removed as of Perl v5.24. It was very similar to
47ed9d9e
KW
876matching against S<C<qr/ ^ [[:xdigit:]]+ $ /x>>, which you should
877convert to use instead. See L<perlrecharclass/POSIX Character Classes>.
37120919 878
9d233e12
JH
879=item C<j0>
880
98ab3abf
AP
881=item C<j1>
882
883=item C<jn>
884
885=item C<y0>
886
887=item C<y1>
888
889=item C<yn>
9d233e12
JH
890
891The Bessel function of the first kind of the order zero.
892
41cd218c 893=item C<kill>
37120919 894
4755096e 895This is identical to Perl's builtin C<kill()> function for sending
c2e66d9e 896signals to processes (often to terminate them), see L<perlfunc/kill>.
37120919 897
41cd218c 898=item C<labs>
37120919 899
4d0de388 900Not implemented. (For returning absolute values of long integers.)
41cd218c 901C<labs()> is C-specific, see L<perlfunc/abs> instead.
37120919 902
41cd218c 903=item C<lchown>
c5eef087
DFC
904
905This is identical to the C function, except the order of arguments is
906consistent with Perl's builtin C<chown()> with the added restriction
4d0de388
KW
907of only one path, not a list of paths. Does the same thing as the
908C<chown()> function but changes the owner of a symbolic link instead
c5eef087
DFC
909of the file the symbolic link points to.
910
4d0de388
KW
911 POSIX::lchown($uid, $gid, $file_path);
912
41cd218c 913=item C<ldexp>
37120919 914
4755096e
GS
915This is identical to the C function C<ldexp()>
916for multiplying floating point numbers with powers of two.
917
918 $x_quadrupled = POSIX::ldexp($x, 2);
37120919 919
41cd218c 920=item C<ldiv>
37120919 921
4d0de388 922Not implemented. (For computing dividends of long integers.)
41cd218c 923C<ldiv()> is C-specific, use C</> and C<int()> instead.
37120919 924
9d233e12
JH
925=item C<lgamma>
926
912a1e06 927The logarithm of the Gamma function [C99]. Added in Perl v5.22.
9d233e12
JH
928
929See also L</tgamma>.
930
931=item C<log1p>
932
4d0de388 933Equivalent to S<C<log(1 + x)>>, but more stable results for small argument
912a1e06 934values [C99]. Added in Perl v5.22.
9d233e12
JH
935
936=item C<log2>
937
912a1e06 938Logarithm base two [C99]. Added in Perl v5.22.
9d233e12
JH
939
940See also L</expm1>.
941
942=item C<logb>
943
912a1e06 944Integer binary logarithm [C99]. Added in Perl v5.22.
9d233e12 945
4d0de388 946For example C<logb(20)> is 4, as a floating point number.
351ab2ad
JH
947
948See also L</ilogb>.
9d233e12 949
41cd218c 950=item C<link>
37120919 951
4755096e
GS
952This is identical to Perl's builtin C<link()> function
953for creating hard links into files, see L<perlfunc/link>.
37120919 954
41cd218c 955=item C<localeconv>
37120919 956
cb1a09d0 957Get numeric formatting information. Returns a reference to a hash
f6fc135b
KW
958containing the formatting values of the locale that currently underlies
959the program, regardless of whether or not it is called from within the
960scope of a S<C<use locale>>. Users of this function should also read
961L<perllocale>, which provides a comprehensive discussion of Perl locale
962handling, including
dfcc8045 963L<a section devoted to this function|perllocale/The localeconv function>.
e9bc6d6b 964Prior to Perl 5.28, or when operating in a non thread-safe environment,
8b24ca2d 965it should not be used in a threaded application unless it's certain that
aa2bc4d3
KW
966the underlying locale is C or POSIX. This is because it otherwise
967changes the locale, which globally affects all threads simultaneously.
69c5e0db
KW
968Windows platforms starting with Visual Studio 2005 are mostly
969thread-safe, but use of this function in those prior to Visual Studio
71c3d40b 9702015 can interfere with a thread that has called
69c5e0db 971L<perlapi/switch_to_global_locale>.
cb1a09d0 972
4755096e 973Here is how to query the database for the B<de> (Deutsch or German) locale.
cb1a09d0 974
c4e34987
DP
975 my $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" );
976 print "Locale: \"$loc\"\n";
977 my $lconv = POSIX::localeconv();
978 foreach my $property (qw(
979 decimal_point
980 thousands_sep
981 grouping
982 int_curr_symbol
983 currency_symbol
984 mon_decimal_point
985 mon_thousands_sep
986 mon_grouping
987 positive_sign
988 negative_sign
989 int_frac_digits
990 frac_digits
991 p_cs_precedes
992 p_sep_by_space
993 n_cs_precedes
994 n_sep_by_space
995 p_sign_posn
996 n_sign_posn
b15c1b56
AF
997 int_p_cs_precedes
998 int_p_sep_by_space
999 int_n_cs_precedes
1000 int_n_sep_by_space
1001 int_p_sign_posn
1002 int_n_sign_posn
c4e34987
DP
1003 ))
1004 {
b70c169c
FC
1005 printf qq(%s: "%s",\n),
1006 $property, $lconv->{$property};
c4e34987 1007 }
37120919 1008
4d0de388
KW
1009The members whose names begin with C<int_p_> and C<int_n_> were added by
1010POSIX.1-2008 and are only available on systems that support them.
b15c1b56 1011
41cd218c 1012=item C<localtime>
37120919 1013
4755096e 1014This is identical to Perl's builtin C<localtime()> function for
dc416353
JK
1015converting seconds since the epoch to a date see L<perlfunc/localtime> except
1016that C<POSIX::localtime()> must be provided an explicit value (rather than
bda53d3e 1017relying on an implicit C<$_>):
dc416353 1018
bda53d3e 1019 @localtime = POSIX::localtime(time); # good
dc416353 1020
bda53d3e 1021 @localtime = localtime(); # good
dc416353 1022
bda53d3e 1023 @localtime = POSIX::localtime(); # throws exception
37120919 1024
41cd218c 1025=item C<log>
37120919 1026
4755096e
GS
1027This is identical to Perl's builtin C<log()> function,
1028returning the natural (I<e>-based) logarithm of the numerical argument,
1029see L<perlfunc/log>.
37120919 1030
41cd218c 1031=item C<log10>
37120919 1032
4755096e
GS
1033This is identical to the C function C<log10()>,
1034returning the 10-base logarithm of the numerical argument.
1035You can also use
1036
1037 sub log10 { log($_[0]) / log(10) }
1038
1039or
1040
3609ea0d 1041 sub log10 { log($_[0]) / 2.30258509299405 }
4755096e
GS
1042
1043or
1044
1045 sub log10 { log($_[0]) * 0.434294481903252 }
37120919 1046
41cd218c 1047=item C<longjmp>
37120919 1048
4d0de388 1049Not implemented. C<longjmp()> is C-specific: use L<perlfunc/die> instead.
37120919 1050
41cd218c 1051=item C<lseek>
37120919 1052
8903cb82 1053Move the file's read/write position. This uses file descriptors such as
cb1a09d0
AD
1054those obtained by calling C<POSIX::open>.
1055
1056 $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
1057 $off_t = POSIX::lseek( $fd, 0, &POSIX::SEEK_SET );
37120919
AD
1058
1059Returns C<undef> on failure.
1060
9d233e12
JH
1061=item C<lrint>
1062
351ab2ad
JH
1063Depending on the current floating point rounding mode, rounds the
1064argument either toward nearest (like L</round>), toward zero (like
1065L</trunc>), downward (toward negative infinity), or upward (toward
912a1e06 1066positive infinity) [C99]. Added in Perl v5.22.
9d233e12 1067
351ab2ad 1068For the rounding mode, see L</fegetround>.
9d233e12 1069
9e010b89
JH
1070=item C<lround>
1071
912a1e06
DB
1072Like L</round>, but as integer, as opposed to floating point [C99]. Added
1073in Perl v5.22.
9e010b89
JH
1074
1075See also L</ceil>, L</floor>, L</trunc>.
1076
25a9f0e7
AC
1077Owing to an oversight, this is not currently exported by default, or as part of
1078the C<:math_h_c99> export tag; importing it must therefore be done by explicit
abc9e18b 1079name.
25a9f0e7 1080
41cd218c 1081=item C<malloc>
37120919 1082
4d0de388 1083Not implemented. C<malloc()> is C-specific. Perl does memory management transparently.
37120919 1084
41cd218c 1085=item C<mblen>
37120919 1086
d2c9cb53
KW
1087This is the same as the C function C<mblen()> on unthreaded perls. On
1088threaded perls, it transparently (almost) substitutes the more
1089thread-safe L<C<mbrlen>(3)>, if available, instead of C<mblen>.
1090
1091Core Perl does not have any support for wide and multibyte locales,
1092except Unicode UTF-8 locales. This function, in conjunction with
1093L</mbtowc> and L</wctomb> may be used to roll your own decoding/encoding
1094of other types of multi-byte locales.
1095
1096Use C<undef> as the first parameter to this function to get the effect
1097of passing NULL as the first parameter to C<mblen>. This resets any
1098shift state to its initial value. The return value is undefined if
1099C<mbrlen> was substituted, so you should never rely on it.
1100
1101When the first parameter is a scalar containing a value that either is a
1102PV string or can be forced into one, the return value is the number of
1103bytes occupied by the first character of that string; or 0 if that first
1104character is the wide NUL character; or negative if there is an error.
1105This is based on the locale that currently underlies the program,
1106regardless of whether or not the function is called from Perl code that
1107is within the scope of S<C<use locale>>. Perl makes no attempt at
1108hiding from your code any differences in the C<errno> setting between
1109C<mblen> and C<mbrlen>. It does set C<errno> to 0 before calling them.
37120919 1110
63bebc14
KW
1111The optional second parameter is ignored if it is larger than the
1112actual length of the first parameter string.
37120919 1113
41cd218c 1114=item C<mbtowc>
37120919 1115
5a6637f0
KW
1116This is the same as the C function C<mbtowc()> on unthreaded perls. On
1117threaded perls, it transparently (almost) substitutes the more
1118thread-safe L<C<mbrtowc>(3)>, if available, instead of C<mbtowc>.
351ab2ad 1119
5a6637f0
KW
1120Core Perl does not have any support for wide and multibyte locales,
1121except Unicode UTF-8 locales. This function, in conjunction with
1122L</mblen> and L</wctomb> may be used to roll your own decoding/encoding
1123of other types of multi-byte locales.
1124
1125The first parameter is a scalar into which, upon success, the wide
1126character represented by the multi-byte string contained in the second
1127parameter is stored. The optional third parameter is ignored if it is
1128larger than the actual length of the second parameter string.
1129
1130Use C<undef> as the second parameter to this function to get the effect
1131of passing NULL as the second parameter to C<mbtowc>. This resets any
1132shift state to its initial value. The return value is undefined if
1133C<mbrtowc> was substituted, so you should never rely on it.
1134
1135When the second parameter is a scalar containing a value that either is
1136a PV string or can be forced into one, the return value is the number of
1137bytes occupied by the first character of that string; or 0 if that first
1138character is the wide NUL character; or negative if there is an error.
1139This is based on the locale that currently underlies the program,
1140regardless of whether or not the function is called from Perl code that
1141is within the scope of S<C<use locale>>. Perl makes no attempt at
1142hiding from your code any differences in the C<errno> setting between
1143C<mbtowc> and C<mbrtowc>. It does set C<errno> to 0 before calling
1144them.
37120919 1145
41cd218c 1146=item C<memchr>
37120919 1147
4d0de388 1148Not implemented. C<memchr()> is C-specific, see L<perlfunc/index> instead.
37120919 1149
41cd218c 1150=item C<memcmp>
37120919 1151
4d0de388 1152Not implemented. C<memcmp()> is C-specific, use C<eq> instead, see L<perlop>.
37120919 1153
41cd218c 1154=item C<memcpy>
37120919 1155
4d0de388 1156Not implemented. C<memcpy()> is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
37120919 1157
41cd218c 1158=item C<memmove>
37120919 1159
4d0de388 1160Not implemented. C<memmove()> is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
37120919 1161
41cd218c 1162=item C<memset>
37120919 1163
4d0de388 1164Not implemented. C<memset()> is C-specific, use C<x> instead, see L<perlop>.
37120919 1165
41cd218c 1166=item C<mkdir>
37120919 1167
4755096e
GS
1168This is identical to Perl's builtin C<mkdir()> function
1169for creating directories, see L<perlfunc/mkdir>.
37120919 1170
41cd218c 1171=item C<mkfifo>
37120919 1172
4755096e
GS
1173This is similar to the C function C<mkfifo()> for creating
1174FIFO special files.
37120919 1175
4755096e
GS
1176 if (mkfifo($path, $mode)) { ....
1177
1178Returns C<undef> on failure. The C<$mode> is similar to the
220f811a
JH
1179mode of C<mkdir()>, see L<perlfunc/mkdir>, though for C<mkfifo>
1180you B<must> specify the C<$mode>.
37120919 1181
41cd218c 1182=item C<mktime>
37120919 1183
cb1a09d0
AD
1184Convert date/time info to a calendar time.
1185
1186Synopsis:
1187
b70c169c
FC
1188 mktime(sec, min, hour, mday, mon, year, wday = 0,
1189 yday = 0, isdst = -1)
cb1a09d0 1190
4d0de388
KW
1191The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero,
1192I<i.e.>, January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
1193year (C<year>) is given in years since 1900; I<i.e.>, the year 1995 is 95; the
cb1a09d0
AD
1194year 2001 is 101. Consult your system's C<mktime()> manpage for details
1195about these and the other arguments.
1196
1197Calendar time for December 12, 1995, at 10:30 am.
1198
1199 $time_t = POSIX::mktime( 0, 30, 10, 12, 11, 95 );
1200 print "Date = ", POSIX::ctime($time_t);
37120919
AD
1201
1202Returns C<undef> on failure.
1203
41cd218c 1204=item C<modf>
37120919 1205
cb1a09d0
AD
1206Return the integral and fractional parts of a floating-point number.
1207
1208 ($fractional, $integral) = POSIX::modf( 3.14 );
37120919 1209
351ab2ad
JH
1210See also L</round>.
1211
d7a0f0b0
JH
1212=item C<NaN>
1213
1214The not-a-number as a constant:
1215
1216 use POSIX qw(NaN);
1217 my $nan = NaN;
1218
1219See also L</nan>, C</isnan>, and L</fpclassify>.
1220
9d233e12
JH
1221=item C<nan>
1222
07bb61ac
JH
1223 my $nan = nan();
1224
912a1e06 1225Returns C<NaN>, not-a-number [C99]. Added in Perl v5.22.
07bb61ac
JH
1226
1227The returned NaN is always a I<quiet> NaN, as opposed to I<signaling>.
1228
1229With an argument, can be used to generate a NaN with I<payload>.
1230The argument is first interpreted as a floating point number,
1231but then any fractional parts are truncated (towards zero),
1232and the value is interpreted as an unsigned integer.
1233The bits of this integer are stored in the unused bits of the NaN.
1234
1235The result has a dual nature: it is a NaN, but it also carries
1236the integer inside it. The integer can be retrieved with L</getpayload>.
1237Note, though, that the payload is not propagated, not even on copies,
1238and definitely not in arithmetic operations.
1239
1240How many bits fit in the NaN depends on what kind of floating points
1241are being used, but on the most common platforms (64-bit IEEE 754,
1242or the x86 80-bit long doubles) there are 51 and 61 bits available,
1243respectively. (There would be 52 and 62, but the quiet/signaling
1244bit of NaNs takes away one.) However, because of the floating-point-to-
1245integer-and-back conversions, please test carefully whether you get back
1246what you put in. If your integers are only 32 bits wide, you probably
1247should not rely on more than 32 bits of payload.
9d233e12 1248
07bb61ac
JH
1249Whether a "signaling" NaN is in any way different from a "quiet" NaN,
1250depends on the platform. Also note that the payload of the default
1251NaN (no argument to nan()) is not necessarily zero, use C<setpayload>
8384a6d6
JH
1252to explicitly set the payload. On some platforms like the 32-bit x86,
1253(unless using the 80-bit long doubles) the signaling bit is not supported
1254at all.
07bb61ac 1255
d7a0f0b0 1256See also L</isnan>, L</NaN>, L</setpayload> and L</issignaling>.
351ab2ad 1257
9d233e12
JH
1258=item C<nearbyint>
1259
1260Returns the nearest integer to the argument, according to the current
912a1e06 1261rounding mode (see L</fegetround>) [C99]. Added in Perl v5.22.
9d233e12
JH
1262
1263=item C<nextafter>
1264
4d0de388 1265Returns the next representable floating point number after C<x> in the
912a1e06 1266direction of C<y> [C99]. Added in Perl v5.22.
4d0de388
KW
1267
1268 my $nextafter = POSIX::nextafter($x, $y);
9d233e12
JH
1269
1270Like L</nexttoward>, but potentially less accurate.
1271
1272=item C<nexttoward>
1273
4d0de388 1274Returns the next representable floating point number after C<x> in the
912a1e06 1275direction of C<y> [C99]. Added in Perl v5.22.
4d0de388
KW
1276
1277 my $nexttoward = POSIX::nexttoward($x, $y);
9d233e12
JH
1278
1279Like L</nextafter>, but potentially more accurate.
1280
41cd218c 1281=item C<nice>
37120919 1282
4755096e
GS
1283This is similar to the C function C<nice()>, for changing
1284the scheduling preference of the current process. Positive
4d0de388
KW
1285arguments mean a more polite process, negative values a more
1286needy process. Normal (non-root) user processes can only change towards
1287being more polite.
37120919
AD
1288
1289Returns C<undef> on failure.
1290
41cd218c 1291=item C<offsetof>
37120919 1292
4d0de388 1293Not implemented. C<offsetof()> is C-specific, you probably want to see L<perlfunc/pack> instead.
37120919 1294
41cd218c 1295=item C<open>
37120919 1296
cb1a09d0
AD
1297Open a file for reading for writing. This returns file descriptors, not
1298Perl filehandles. Use C<POSIX::close> to close the file.
1299
1300Open a file read-only with mode 0666.
1301
1302 $fd = POSIX::open( "foo" );
1303
1304Open a file for read and write.
1305
1306 $fd = POSIX::open( "foo", &POSIX::O_RDWR );
1307
1308Open a file for write, with truncation.
1309
b70c169c
FC
1310 $fd = POSIX::open(
1311 "foo", &POSIX::O_WRONLY | &POSIX::O_TRUNC
1312 );
cb1a09d0
AD
1313
1314Create a new file with mode 0640. Set up the file for writing.
1315
b70c169c
FC
1316 $fd = POSIX::open(
1317 "foo", &POSIX::O_CREAT | &POSIX::O_WRONLY, 0640
1318 );
37120919
AD
1319
1320Returns C<undef> on failure.
1321
4755096e
GS
1322See also L<perlfunc/sysopen>.
1323
41cd218c 1324=item C<opendir>
37120919 1325
cb1a09d0
AD
1326Open a directory for reading.
1327
2359510d 1328 $dir = POSIX::opendir( "/var" );
cb1a09d0
AD
1329 @files = POSIX::readdir( $dir );
1330 POSIX::closedir( $dir );
1331
1332Returns C<undef> on failure.
37120919 1333
41cd218c 1334=item C<pathconf>
37120919
AD
1335
1336Retrieves the value of a configurable limit on a file or directory.
1337
1338The following will determine the maximum length of the longest allowable
2359510d 1339pathname on the filesystem which holds C</var>.
37120919 1340
b70c169c
FC
1341 $path_max = POSIX::pathconf( "/var",
1342 &POSIX::_PC_PATH_MAX );
37120919
AD
1343
1344Returns C<undef> on failure.
1345
41cd218c 1346=item C<pause>
37120919 1347
4755096e
GS
1348This is similar to the C function C<pause()>, which suspends
1349the execution of the current process until a signal is received.
37120919
AD
1350
1351Returns C<undef> on failure.
1352
41cd218c 1353=item C<perror>
37120919 1354
4755096e 1355This is identical to the C function C<perror()>, which outputs to the
41cd218c 1356standard error stream the specified message followed by C<": "> and the
4755096e
GS
1357current error string. Use the C<warn()> function and the C<$!>
1358variable instead, see L<perlfunc/warn> and L<perlvar/$ERRNO>.
37120919 1359
41cd218c 1360=item C<pipe>
37120919 1361
cb1a09d0
AD
1362Create an interprocess channel. This returns file descriptors like those
1363returned by C<POSIX::open>.
1364
b27d06da
MS
1365 my ($read, $write) = POSIX::pipe();
1366 POSIX::write( $write, "hello", 5 );
1367 POSIX::read( $read, $buf, 5 );
37120919 1368
4755096e
GS
1369See also L<perlfunc/pipe>.
1370
41cd218c 1371=item C<pow>
37120919 1372
4755096e 1373Computes C<$x> raised to the power C<$exponent>.
37120919
AD
1374
1375 $ret = POSIX::pow( $x, $exponent );
1376
4755096e
GS
1377You can also use the C<**> operator, see L<perlop>.
1378
41cd218c 1379=item C<printf>
37120919 1380
4d0de388 1381Formats and prints the specified arguments to C<STDOUT>.
4755096e 1382See also L<perlfunc/printf>.
37120919 1383
41cd218c 1384=item C<putc>
37120919 1385
4d0de388 1386Not implemented. C<putc()> is C-specific, see L<perlfunc/print> instead.
37120919 1387
41cd218c 1388=item C<putchar>
37120919 1389
4d0de388 1390Not implemented. C<putchar()> is C-specific, see L<perlfunc/print> instead.
37120919 1391
41cd218c 1392=item C<puts>
37120919 1393
4d0de388 1394Not implemented. C<puts()> is C-specific, see L<perlfunc/print> instead.
37120919 1395
41cd218c 1396=item C<qsort>
37120919 1397
4d0de388 1398Not implemented. C<qsort()> is C-specific, see L<perlfunc/sort> instead.
37120919 1399
41cd218c 1400=item C<raise>
37120919
AD
1401
1402Sends the specified signal to the current process.
4755096e 1403See also L<perlfunc/kill> and the C<$$> in L<perlvar/$PID>.
37120919 1404
41cd218c 1405=item C<rand>
37120919 1406
4d0de388 1407Not implemented. C<rand()> is non-portable, see L<perlfunc/rand> instead.
37120919 1408
41cd218c 1409=item C<read>
37120919 1410
cb1a09d0
AD
1411Read from a file. This uses file descriptors such as those obtained by
1412calling C<POSIX::open>. If the buffer C<$buf> is not large enough for the
1413read then Perl will extend it to make room for the request.
1414
1415 $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
1416 $bytes = POSIX::read( $fd, $buf, 3 );
37120919
AD
1417
1418Returns C<undef> on failure.
1419
4755096e
GS
1420See also L<perlfunc/sysread>.
1421
41cd218c 1422=item C<readdir>
37120919 1423
4755096e
GS
1424This is identical to Perl's builtin C<readdir()> function
1425for reading directory entries, see L<perlfunc/readdir>.
37120919 1426
41cd218c 1427=item C<realloc>
37120919 1428
4d0de388 1429Not implemented. C<realloc()> is C-specific. Perl does memory management transparently.
37120919 1430
9d233e12
JH
1431=item C<remainder>
1432
4d0de388 1433Given C<x> and C<y>, returns the value S<C<x - n*y>>, where C<n> is the integer
912a1e06 1434closest to C<x>/C<y> [C99]. Added in Perl v5.22.
4d0de388
KW
1435
1436 my $remainder = POSIX::remainder($x, $y)
9d233e12
JH
1437
1438See also L</remquo>.
1439
41cd218c 1440=item C<remove>
37120919 1441
c6f0b8ca
TC
1442Deletes a name from the filesystem. Calls L<perlfunc/unlink> for
1443files and L<perlfunc/rmdir> for directories.
37120919 1444
9d233e12
JH
1445=item C<remquo>
1446
1447Like L</remainder> but also returns the low-order bits of the quotient (n)
912a1e06 1448[C99]. Added in Perl v5.22.
9d233e12
JH
1449
1450(This is quite esoteric interface, mainly used to implement numerical
1451algorithms.)
1452
41cd218c 1453=item C<rename>
37120919 1454
4755096e
GS
1455This is identical to Perl's builtin C<rename()> function
1456for renaming files, see L<perlfunc/rename>.
37120919 1457
41cd218c 1458=item C<rewind>
37120919
AD
1459
1460Seeks to the beginning of the file.
1461
41cd218c 1462=item C<rewinddir>
37120919 1463
4755096e
GS
1464This is identical to Perl's builtin C<rewinddir()> function for
1465rewinding directory entry streams, see L<perlfunc/rewinddir>.
37120919 1466
9d233e12
JH
1467=item C<rint>
1468
1469Identical to L</lrint>.
1470
41cd218c 1471=item C<rmdir>
37120919 1472
4755096e
GS
1473This is identical to Perl's builtin C<rmdir()> function
1474for removing (empty) directories, see L<perlfunc/rmdir>.
37120919 1475
9d233e12
JH
1476=item C<round>
1477
9e010b89 1478Returns the integer (but still as floating point) nearest to the
912a1e06 1479argument [C99]. Added in Perl v5.22.
9d233e12 1480
351ab2ad 1481See also L</ceil>, L</floor>, L</lround>, L</modf>, and L</trunc>.
9d233e12
JH
1482
1483=item C<scalbn>
1484
912a1e06 1485Returns S<C<x * 2**y>> [C99]. Added in Perl v5.22.
9d233e12
JH
1486
1487See also L</frexp> and L</ldexp>.
1488
41cd218c 1489=item C<scanf>
37120919 1490
4d0de388 1491Not implemented. C<scanf()> is C-specific, use E<lt>E<gt> and regular expressions instead,
4755096e 1492see L<perlre>.
37120919 1493
41cd218c 1494=item C<setgid>
37120919 1495
a043a685
GW
1496Sets the real group identifier and the effective group identifier for
1497this process. Similar to assigning a value to the Perl's builtin
2bc0d022 1498C<$)> variable, see L<perlvar/$EGID>, except that the latter
a043a685
GW
1499will change only the real user identifier, and that the setgid()
1500uses only a single numeric argument, as opposed to a space-separated
1501list of numbers.
37120919 1502
41cd218c 1503=item C<setjmp>
37120919 1504
4d0de388 1505Not implemented. C<setjmp()> is C-specific: use C<eval {}> instead,
4755096e 1506see L<perlfunc/eval>.
37120919 1507
41cd218c 1508=item C<setlocale>
37120919 1509
06283613
KW
1510WARNING! Prior to Perl 5.28 or on a system that does not support
1511thread-safe locale operations, do NOT use this function in a
1512L<thread|threads>. The locale will change in all other threads at the
1513same time, and should your thread get paused by the operating system,
1514and another started, that thread will not have the locale it is
1515expecting. On some platforms, there can be a race leading to segfaults
5f08f0bb
KW
1516if two threads call this function nearly simultaneously. This warning
1517does not apply on unthreaded builds, or on perls where
1518C<${^SAFE_LOCALES}> exists and is non-zero; namely Perl 5.28 and later
1519compiled to be locale-thread-safe.
06283613
KW
1520
1521This function
1522modifies and queries the program's underlying locale. Users of this
dfcc8045
KW
1523function should read L<perllocale>, whch provides a comprehensive
1524discussion of Perl locale handling, knowledge of which is necessary to
1525properly use this function. It contains
1526L<a section devoted to this function|perllocale/The setlocale function>.
1527The discussion here is merely a summary reference for C<setlocale()>.
6ea81ccf
KW
1528Note that Perl itself is almost entirely unaffected by the locale
1529except within the scope of S<C<"use locale">>. (Exceptions are listed
06283613
KW
1530in L<perllocale/Not within the scope of "use locale">, and
1531locale-dependent functions within the POSIX module ARE always affected
1532by the current locale.)
6ea81ccf
KW
1533
1534The following examples assume
c26abfa6
JH
1535
1536 use POSIX qw(setlocale LC_ALL LC_CTYPE);
1537
1538has been issued.
37120919 1539
8966fa01
JH
1540The following will set the traditional UNIX system locale behavior
1541(the second argument C<"C">).
37120919 1542
c26abfa6 1543 $loc = setlocale( LC_ALL, "C" );
37120919 1544
41cd218c 1545The following will query the current C<LC_CTYPE> category. (No second
c26abfa6 1546argument means 'query'.)
8966fa01 1547
c26abfa6 1548 $loc = setlocale( LC_CTYPE );
8966fa01 1549
41cd218c 1550The following will set the C<LC_CTYPE> behaviour according to the locale
8966fa01 1551environment variables (the second argument C<"">).
4c9b78f4 1552Please see your system's C<setlocale(3)> documentation for the locale
71be2cbc 1553environment variables' meaning or consult L<perllocale>.
8966fa01 1554
c26abfa6 1555 $loc = setlocale( LC_CTYPE, "" );
8966fa01 1556
41cd218c 1557The following will set the C<LC_COLLATE> behaviour to Argentinian
8966fa01 1558Spanish. B<NOTE>: The naming and availability of locales depends on
71be2cbc 1559your operating system. Please consult L<perllocale> for how to find
8966fa01
JH
1560out which locales are available in your system.
1561
801ed997 1562 $loc = setlocale( LC_COLLATE, "es_AR.ISO8859-1" );
8966fa01 1563
07bb61ac
JH
1564=item C<setpayload>
1565
1566 use POSIX ':nan_payload';
1567 setpayload($var, $payload);
1568
912a1e06 1569Sets the C<NaN> payload of var. Added in Perl v5.24.
07bb61ac
JH
1570
1571NOTE: the NaN payload APIs are based on the latest (as of June 2015)
1572proposed ISO C interfaces, but they are not yet a standard. Things
1573may change.
1574
1575See L</nan> for more discussion about C<NaN>.
1576
1577See also L</setpayloadsig>, L</isnan>, L</getpayload>, and L</issignaling>.
1578
1579=item C<setpayloadsig>
1580
1581 use POSIX ':nan_payload';
1582 setpayloadsig($var, $payload);
1583
912a1e06
DB
1584Like L</setpayload> but also makes the NaN I<signaling>. Added in Perl
1585v5.24.
07bb61ac
JH
1586
1587Depending on the platform the NaN may or may not behave differently.
1588
1589Note the API instability warning in L</setpayload>.
1590
1591Note that because how the floating point formats work out, on the most
1592common platforms signaling payload of zero is best avoided,
1593since it might end up being identical to C<+Inf>.
1594
1595See also L</nan>, L</isnan>, L</getpayload>, and L</issignaling>.
1596
41cd218c 1597=item C<setpgid>
37120919 1598
4755096e
GS
1599This is similar to the C function C<setpgid()> for
1600setting the process group identifier of the current process.
37120919
AD
1601
1602Returns C<undef> on failure.
1603
41cd218c 1604=item C<setsid>
37120919 1605
4755096e
GS
1606This is identical to the C function C<setsid()> for
1607setting the session identifier of the current process.
37120919 1608
41cd218c 1609=item C<setuid>
37120919 1610
a043a685
GW
1611Sets the real user identifier and the effective user identifier for
1612this process. Similar to assigning a value to the Perl's builtin
1613C<$E<lt>> variable, see L<perlvar/$UID>, except that the latter
1614will change only the real user identifier.
37120919 1615
41cd218c 1616=item C<sigaction>
37120919 1617
3609ea0d
JH
1618Detailed signal management. This uses C<POSIX::SigAction> objects for
1619the C<action> and C<oldaction> arguments (the oldaction can also be
1620just a hash reference). Consult your system's C<sigaction> manpage
1621for details, see also C<POSIX::SigRt>.
cb1a09d0
AD
1622
1623Synopsis:
1624
1d81eac9 1625 sigaction(signal, action, oldaction = 0)
37120919 1626
1d81eac9 1627Returns C<undef> on failure. The C<signal> must be a number (like
41cd218c 1628C<SIGHUP>), not a string (like C<"SIGHUP">), though Perl does try hard
1d81eac9 1629to understand you.
37120919 1630
41cd218c 1631If you use the C<SA_SIGINFO> flag, the signal handler will in addition to
8aad04aa
JH
1632the first argument, the signal name, also receive a second argument, a
1633hash reference, inside which are the following keys with the following
1634semantics, as defined by POSIX/SUSv3:
1635
1636 signo the signal number
1637 errno the error number
1638 code if this is zero or less, the signal was sent by
1639 a user process and the uid and pid make sense,
1640 otherwise the signal was sent by the kernel
79dec0f4 1641
34e79b75 1642The constants for specific C<code> values can be imported individually
912a1e06 1643or using the C<:signal_h_si_code> tag, since Perl v5.24.
34e79b75 1644
79dec0f4
JH
1645The following are also defined by POSIX/SUSv3, but unfortunately
1646not very widely implemented:
1647
8aad04aa
JH
1648 pid the process id generating the signal
1649 uid the uid of the process id generating the signal
1650 status exit value or signal for SIGCHLD
1651 band band event for SIGPOLL
408b5f5e
KW
1652 addr address of faulting instruction or memory
1653 reference for SIGILL, SIGFPE, SIGSEGV or SIGBUS
8aad04aa
JH
1654
1655A third argument is also passed to the handler, which contains a copy
41cd218c
KW
1656of the raw binary contents of the C<siginfo> structure: if a system has
1657some non-POSIX fields, this third argument is where to C<unpack()> them
8aad04aa
JH
1658from.
1659
41cd218c 1660Note that not all C<siginfo> values make sense simultaneously (some are
8aad04aa
JH
1661valid only for certain signals, for example), and not all values make
1662sense from Perl perspective, you should to consult your system's
1663C<sigaction> and possibly also C<siginfo> documentation.
1664
41cd218c 1665=item C<siglongjmp>
37120919 1666
4d0de388 1667Not implemented. C<siglongjmp()> is C-specific: use L<perlfunc/die> instead.
37120919 1668
9d233e12
JH
1669=item C<signbit>
1670
1671Returns zero for positive arguments, non-zero for negative arguments [C99].
912a1e06 1672Added in Perl v5.22.
9d233e12 1673
41cd218c 1674=item C<sigpending>
37120919 1675
cb1a09d0
AD
1676Examine signals that are blocked and pending. This uses C<POSIX::SigSet>
1677objects for the C<sigset> argument. Consult your system's C<sigpending>
1678manpage for details.
1679
1680Synopsis:
1681
1682 sigpending(sigset)
37120919
AD
1683
1684Returns C<undef> on failure.
1685
41cd218c 1686=item C<sigprocmask>
37120919 1687
cb1a09d0
AD
1688Change and/or examine calling process's signal mask. This uses
1689C<POSIX::SigSet> objects for the C<sigset> and C<oldsigset> arguments.
1690Consult your system's C<sigprocmask> manpage for details.
1691
1692Synopsis:
1693
1694 sigprocmask(how, sigset, oldsigset = 0)
37120919
AD
1695
1696Returns C<undef> on failure.
1697
faaf6836
LT
1698Note that you can't reliably block or unblock a signal from its own signal
1699handler if you're using safe signals. Other signals can be blocked or unblocked
1700reliably.
1701
41cd218c 1702=item C<sigsetjmp>
37120919 1703
4d0de388 1704Not implemented. C<sigsetjmp()> is C-specific: use C<eval {}> instead,
4755096e 1705see L<perlfunc/eval>.
37120919 1706
41cd218c 1707=item C<sigsuspend>
37120919 1708
cb1a09d0
AD
1709Install a signal mask and suspend process until signal arrives. This uses
1710C<POSIX::SigSet> objects for the C<signal_mask> argument. Consult your
1711system's C<sigsuspend> manpage for details.
1712
1713Synopsis:
1714
1715 sigsuspend(signal_mask)
37120919
AD
1716
1717Returns C<undef> on failure.
1718
41cd218c 1719=item C<sin>
37120919 1720
4755096e
GS
1721This is identical to Perl's builtin C<sin()> function
1722for returning the sine of the numerical argument,
c2e66d9e 1723see L<perlfunc/sin>. See also L<Math::Trig>.
37120919 1724
41cd218c 1725=item C<sinh>
37120919 1726
4755096e
GS
1727This is identical to the C function C<sinh()>
1728for returning the hyperbolic sine of the numerical argument.
c2e66d9e 1729See also L<Math::Trig>.
37120919 1730
41cd218c 1731=item C<sleep>
37120919 1732
2ab27a20
A
1733This is functionally identical to Perl's builtin C<sleep()> function
1734for suspending the execution of the current for process for certain
3609ea0d 1735number of seconds, see L<perlfunc/sleep>. There is one significant
2bad225e 1736difference, however: C<POSIX::sleep()> returns the number of
2ab27a20
A
1737B<unslept> seconds, while the C<CORE::sleep()> returns the
1738number of slept seconds.
37120919 1739
41cd218c 1740=item C<sprintf>
37120919 1741
4755096e
GS
1742This is similar to Perl's builtin C<sprintf()> function
1743for returning a string that has the arguments formatted as requested,
1744see L<perlfunc/sprintf>.
37120919 1745
41cd218c 1746=item C<sqrt>
37120919
AD
1747
1748This is identical to Perl's builtin C<sqrt()> function.
4755096e
GS
1749for returning the square root of the numerical argument,
1750see L<perlfunc/sqrt>.
37120919 1751
41cd218c 1752=item C<srand>
37120919 1753
4755096e 1754Give a seed the pseudorandom number generator, see L<perlfunc/srand>.
37120919 1755
41cd218c 1756=item C<sscanf>
37120919 1757
4d0de388 1758Not implemented. C<sscanf()> is C-specific, use regular expressions instead,
4755096e 1759see L<perlre>.
37120919 1760
41cd218c 1761=item C<stat>
37120919 1762
4755096e 1763This is identical to Perl's builtin C<stat()> function
d7f8936a 1764for returning information about files and directories.
37120919 1765
41cd218c 1766=item C<strcat>
37120919 1767
4d0de388 1768Not implemented. C<strcat()> is C-specific, use C<.=> instead, see L<perlop>.
37120919 1769
41cd218c 1770=item C<strchr>
37120919 1771
4d0de388 1772Not implemented. C<strchr()> is C-specific, see L<perlfunc/index> instead.
37120919 1773
41cd218c 1774=item C<strcmp>
37120919 1775
4d0de388 1776Not implemented. C<strcmp()> is C-specific, use C<eq> or C<cmp> instead, see L<perlop>.
37120919 1777
41cd218c 1778=item C<strcoll>
37120919 1779
4755096e
GS
1780This is identical to the C function C<strcoll()>
1781for collating (comparing) strings transformed using
1782the C<strxfrm()> function. Not really needed since
1783Perl can do this transparently, see L<perllocale>.
37120919 1784
393aa92a
KW
1785Beware that in a UTF-8 locale, anything you pass to this function must
1786be in UTF-8; and when not in a UTF-8 locale, anything passed must not be
1787UTF-8 encoded.
1788
41cd218c 1789=item C<strcpy>
37120919 1790
4d0de388 1791Not implemented. C<strcpy()> is C-specific, use C<=> instead, see L<perlop>.
37120919 1792
41cd218c 1793=item C<strcspn>
37120919 1794
4d0de388 1795Not implemented. C<strcspn()> is C-specific, use regular expressions instead,
4755096e 1796see L<perlre>.
37120919 1797
41cd218c 1798=item C<strerror>
37120919
AD
1799
1800Returns the error string for the specified errno.
4d0de388 1801Identical to the string form of C<$!>, see L<perlvar/$ERRNO>.
37120919 1802
41cd218c 1803=item C<strftime>
37120919 1804
cb1a09d0
AD
1805Convert date and time information to string. Returns the string.
1806
1807Synopsis:
1808
b70c169c
FC
1809 strftime(fmt, sec, min, hour, mday, mon, year,
1810 wday = -1, yday = -1, isdst = -1)
cb1a09d0 1811
4d0de388
KW
1812The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero,
1813I<i.e.>, January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
1814year (C<year>) is given in years since 1900, I<i.e.>, the year 1995 is 95; the
cb1a09d0 1815year 2001 is 101. Consult your system's C<strftime()> manpage for details
659b4938 1816about these and the other arguments.
f14c76ed 1817
659b4938
DD
1818If you want your code to be portable, your format (C<fmt>) argument
1819should use only the conversion specifiers defined by the ANSI C
f14c76ed
RGS
1820standard (C89, to play safe). These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
1821But even then, the B<results> of some of the conversion specifiers are
1822non-portable. For example, the specifiers C<aAbBcpZ> change according
1823to the locale settings of the user, and both how to set locales (the
1824locale names) and what output to expect are non-standard.
1825The specifier C<c> changes according to the timezone settings of the
1826user and the timezone computation rules of the operating system.
1827The C<Z> specifier is notoriously unportable since the names of
1828timezones are non-standard. Sticking to the numeric specifiers is the
1829safest route.
1830
1831The given arguments are made consistent as though by calling
1832C<mktime()> before calling your system's C<strftime()> function,
1833except that the C<isdst> value is not affected.
cb1a09d0
AD
1834
1835The string for Tuesday, December 12, 1995.
1836
b70c169c
FC
1837 $str = POSIX::strftime( "%A, %B %d, %Y",
1838 0, 0, 0, 12, 11, 95, 2 );
cb1a09d0 1839 print "$str\n";
37120919 1840
41cd218c 1841=item C<strlen>
37120919 1842
4d0de388 1843Not implemented. C<strlen()> is C-specific, use C<length()> instead, see L<perlfunc/length>.
37120919 1844
41cd218c 1845=item C<strncat>
37120919 1846
4d0de388 1847Not implemented. C<strncat()> is C-specific, use C<.=> instead, see L<perlop>.
37120919 1848
41cd218c 1849=item C<strncmp>
37120919 1850
4d0de388 1851Not implemented. C<strncmp()> is C-specific, use C<eq> instead, see L<perlop>.
37120919 1852
41cd218c 1853=item C<strncpy>
37120919 1854
4d0de388 1855Not implemented. C<strncpy()> is C-specific, use C<=> instead, see L<perlop>.
37120919 1856
41cd218c 1857=item C<strpbrk>
37120919 1858
4d0de388 1859Not implemented. C<strpbrk()> is C-specific, use regular expressions instead,
4755096e 1860see L<perlre>.
37120919 1861
41cd218c 1862=item C<strrchr>
37120919 1863
4d0de388 1864Not implemented. C<strrchr()> is C-specific, see L<perlfunc/rindex> instead.
37120919 1865
41cd218c 1866=item C<strspn>
37120919 1867
4d0de388 1868Not implemented. C<strspn()> is C-specific, use regular expressions instead,
4755096e 1869see L<perlre>.
37120919 1870
41cd218c 1871=item C<strstr>
37120919 1872
4755096e
GS
1873This is identical to Perl's builtin C<index()> function,
1874see L<perlfunc/index>.
37120919 1875
41cd218c 1876=item C<strtod>
37120919 1877
a89d8a78
DH
1878String to double translation. Returns the parsed number and the number
1879of characters in the unparsed portion of the string. Truly
41cd218c 1880POSIX-compliant systems set C<$!> (C<$ERRNO>) to indicate a translation
4d0de388 1881error, so clear C<$!> before calling C<strtod>. However, non-POSIX systems
41cd218c 1882may not check for overflow, and therefore will never set C<$!>.
a89d8a78 1883
4e6effb7 1884C<strtod> respects any POSIX C<setlocale()> C<LC_NUMERIC> settings,
458680b3 1885regardless of whether or not it is called from Perl code that is within
20e38015
KW
1886the scope of S<C<use locale>>. Prior to Perl 5.28, or when operating in
1887a non thread-safe environment, it should not be used in a threaded
1888application unless it's certain that the underlying locale is C
aa2bc4d3
KW
1889or POSIX. This is because it otherwise changes the locale, which
1890globally affects all threads simultaneously.
a89d8a78 1891
41cd218c 1892To parse a string C<$str> as a floating point number use
a89d8a78
DH
1893
1894 $! = 0;
1895 ($num, $n_unparsed) = POSIX::strtod($str);
1896
41cd218c 1897The second returned item and C<$!> can be used to check for valid input:
a89d8a78 1898
6309100e
DM
1899 if (($str eq '') || ($n_unparsed != 0) || $!) {
1900 die "Non-numeric input $str" . ($! ? ": $!\n" : "\n");
a89d8a78
DH
1901 }
1902
4d0de388 1903When called in a scalar context C<strtod> returns the parsed number.
37120919 1904
41cd218c 1905=item C<strtok>
37120919 1906
4d0de388 1907Not implemented. C<strtok()> is C-specific, use regular expressions instead, see
4755096e 1908L<perlre>, or L<perlfunc/split>.
37120919 1909
41cd218c 1910=item C<strtol>
37120919 1911
a89d8a78
DH
1912String to (long) integer translation. Returns the parsed number and
1913the number of characters in the unparsed portion of the string. Truly
41cd218c
KW
1914POSIX-compliant systems set C<$!> (C<$ERRNO>) to indicate a translation
1915error, so clear C<$!> before calling C<strtol>. However, non-POSIX systems
1916may not check for overflow, and therefore will never set C<$!>.
a89d8a78 1917
41cd218c 1918C<strtol> should respect any POSIX I<setlocale()> settings.
a89d8a78 1919
41cd218c 1920To parse a string C<$str> as a number in some base C<$base> use
a89d8a78
DH
1921
1922 $! = 0;
1923 ($num, $n_unparsed) = POSIX::strtol($str, $base);
1924
1925The base should be zero or between 2 and 36, inclusive. When the base
4d0de388 1926is zero or omitted C<strtol> will use the string itself to determine the
a89d8a78
DH
1927base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
1928octal; any other leading characters mean decimal. Thus, "1234" is
1929parsed as a decimal number, "01234" as an octal number, and "0x1234"
1930as a hexadecimal number.
1931
41cd218c 1932The second returned item and C<$!> can be used to check for valid input:
a89d8a78
DH
1933
1934 if (($str eq '') || ($n_unparsed != 0) || !$!) {
1935 die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
1936 }
1937
4d0de388 1938When called in a scalar context C<strtol> returns the parsed number.
a89d8a78 1939
0ff7b9da
JH
1940=item C<strtold>
1941
1942Like L</strtod> but for long doubles. Defined only if the
1943system supports long doubles.
1944
41cd218c 1945=item C<strtoul>
a89d8a78 1946
41cd218c
KW
1947String to unsigned (long) integer translation. C<strtoul()> is identical
1948to C<strtol()> except that C<strtoul()> only parses unsigned integers. See
4755096e 1949L</strtol> for details.
a89d8a78 1950
41cd218c
KW
1951Note: Some vendors supply C<strtod()> and C<strtol()> but not C<strtoul()>.
1952Other vendors that do supply C<strtoul()> parse "-1" as a valid value.
37120919 1953
41cd218c 1954=item C<strxfrm>
37120919 1955
cb1a09d0
AD
1956String transformation. Returns the transformed string.
1957
1958 $dst = POSIX::strxfrm( $src );
37120919 1959
4755096e
GS
1960Used in conjunction with the C<strcoll()> function, see L</strcoll>.
1961
1962Not really needed since Perl can do this transparently, see
1963L<perllocale>.
1964
393aa92a
KW
1965Beware that in a UTF-8 locale, anything you pass to this function must
1966be in UTF-8; and when not in a UTF-8 locale, anything passed must not be
1967UTF-8 encoded.
1968
41cd218c 1969=item C<sysconf>
37120919
AD
1970
1971Retrieves values of system configurable variables.
1972
1973The following will get the machine's clock speed.
1974
1975 $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );
1976
1977Returns C<undef> on failure.
1978
41cd218c 1979=item C<system>
37120919 1980
4755096e
GS
1981This is identical to Perl's builtin C<system()> function, see
1982L<perlfunc/system>.
37120919 1983
41cd218c 1984=item C<tan>
37120919 1985
4755096e 1986This is identical to the C function C<tan()>, returning the
c2e66d9e 1987tangent of the numerical argument. See also L<Math::Trig>.
37120919 1988
41cd218c 1989=item C<tanh>
37120919 1990
4755096e 1991This is identical to the C function C<tanh()>, returning the
c2e66d9e 1992hyperbolic tangent of the numerical argument. See also L<Math::Trig>.
37120919 1993
41cd218c 1994=item C<tcdrain>
37120919 1995
4755096e
GS
1996This is similar to the C function C<tcdrain()> for draining
1997the output queue of its argument stream.
37120919
AD
1998
1999Returns C<undef> on failure.
2000
41cd218c 2001=item C<tcflow>
37120919 2002
4755096e
GS
2003This is similar to the C function C<tcflow()> for controlling
2004the flow of its argument stream.
37120919
AD
2005
2006Returns C<undef> on failure.
2007
41cd218c 2008=item C<tcflush>
37120919 2009
4755096e 2010This is similar to the C function C<tcflush()> for flushing
cc767757 2011the I/O buffers of its argument stream.
37120919
AD
2012
2013Returns C<undef> on failure.
2014
41cd218c 2015=item C<tcgetpgrp>
37120919 2016
4755096e
GS
2017This is identical to the C function C<tcgetpgrp()> for returning the
2018process group identifier of the foreground process group of the controlling
2019terminal.
37120919 2020
41cd218c 2021=item C<tcsendbreak>
37120919 2022
4755096e
GS
2023This is similar to the C function C<tcsendbreak()> for sending
2024a break on its argument stream.
37120919
AD
2025
2026Returns C<undef> on failure.
2027
41cd218c 2028=item C<tcsetpgrp>
37120919 2029
4755096e
GS
2030This is similar to the C function C<tcsetpgrp()> for setting the
2031process group identifier of the foreground process group of the controlling
2032terminal.
37120919
AD
2033
2034Returns C<undef> on failure.
2035
9d233e12
JH
2036=item C<tgamma>
2037
912a1e06 2038The Gamma function [C99]. Added in Perl v5.22.
9d233e12
JH
2039
2040See also L</lgamma>.
2041
41cd218c 2042=item C<time>
37120919 2043
4755096e
GS
2044This is identical to Perl's builtin C<time()> function
2045for returning the number of seconds since the epoch
2046(whatever it is for the system), see L<perlfunc/time>.
37120919 2047
41cd218c 2048=item C<times>
37120919 2049
41cd218c 2050The C<times()> function returns elapsed realtime since some point in the past
37120919
AD
2051(such as system startup), user and system times for this process, and user
2052and system times used by child processes. All times are returned in clock
2053ticks.
2054
4d0de388 2055 ($realtime, $user, $system, $cuser, $csystem)
b70c169c 2056 = POSIX::times();
37120919
AD
2057
2058Note: Perl's builtin C<times()> function returns four values, measured in
2059seconds.
2060
41cd218c 2061=item C<tmpfile>
37120919 2062
4d0de388 2063Not implemented. Use method C<IO::File::new_tmpfile()> instead, or see L<File::Temp>.
37120919 2064
41cd218c 2065=item C<tmpnam>
37120919 2066
60cba15a 2067For security reasons, which are probably detailed in your system's
41cd218c 2068documentation for the C library C<tmpnam()> function, this interface
912a1e06 2069is no longer available since Perl v5.26; instead use L<File::Temp>.
4755096e 2070
41cd218c 2071=item C<tolower>
37120919 2072
912a1e06 2073This function has been removed as of Perl v5.26.
4755096e 2074This is identical to the C function, except that it can apply to a single
4d0de388
KW
2075character or to a whole string, and currently operates as if the locale
2076always is "C". Consider using the C<lc()> function, see L<perlfunc/lc>,
4755096e
GS
2077see L<perlfunc/lc>, or the equivalent C<\L> operator inside doublequotish
2078strings.
37120919 2079
41cd218c 2080=item C<toupper>
37120919 2081
912a1e06 2082This function has been removed as of Perl v5.26.
4d0de388
KW
2083This is similar to the C function, except that it can apply to a single
2084character or to a whole string, and currently operates as if the locale
2085always is "C". Consider using the C<uc()> function, see L<perlfunc/uc>,
2086or the equivalent C<\U> operator inside doublequotish strings.
37120919 2087
9d233e12
JH
2088=item C<trunc>
2089
912a1e06
DB
2090Returns the integer toward zero from the argument [C99]. Added in Perl
2091v5.22.
9d233e12
JH
2092
2093See also L</ceil>, L</floor>, and L</round>.
2094
41cd218c 2095=item C<ttyname>
37120919 2096
4755096e
GS
2097This is identical to the C function C<ttyname()> for returning the
2098name of the current terminal.
37120919 2099
41cd218c 2100=item C<tzname>
37120919 2101
cb1a09d0
AD
2102Retrieves the time conversion information from the C<tzname> variable.
2103
2104 POSIX::tzset();
2105 ($std, $dst) = POSIX::tzname();
37120919 2106
41cd218c 2107=item C<tzset>
37120919 2108
4755096e
GS
2109This is identical to the C function C<tzset()> for setting
2110the current timezone based on the environment variable C<TZ>,
2111to be used by C<ctime()>, C<localtime()>, C<mktime()>, and C<strftime()>
2112functions.
37120919 2113
41cd218c 2114=item C<umask>
37120919 2115
4755096e
GS
2116This is identical to Perl's builtin C<umask()> function
2117for setting (and querying) the file creation permission mask,
2118see L<perlfunc/umask>.
37120919 2119
41cd218c 2120=item C<uname>
37120919 2121
cb1a09d0
AD
2122Get name of current operating system.
2123
b70c169c
FC
2124 ($sysname, $nodename, $release, $version, $machine)
2125 = POSIX::uname();
4755096e
GS
2126
2127Note that the actual meanings of the various fields are not
2128that well standardized, do not expect any great portability.
2129The C<$sysname> might be the name of the operating system,
2130the C<$nodename> might be the name of the host, the C<$release>
2131might be the (major) release number of the operating system,
2132the C<$version> might be the (minor) release number of the
2133operating system, and the C<$machine> might be a hardware identifier.
2134Maybe.
37120919 2135
41cd218c 2136=item C<ungetc>
37120919 2137
4d0de388 2138Not implemented. Use method C<IO::Handle::ungetc()> instead.
37120919 2139
41cd218c 2140=item C<unlink>
37120919 2141
4755096e
GS
2142This is identical to Perl's builtin C<unlink()> function
2143for removing files, see L<perlfunc/unlink>.
37120919 2144
41cd218c 2145=item C<utime>
37120919 2146
4755096e
GS
2147This is identical to Perl's builtin C<utime()> function
2148for changing the time stamps of files and directories,
2149see L<perlfunc/utime>.
37120919 2150
41cd218c 2151=item C<vfprintf>
37120919 2152
4d0de388 2153Not implemented. C<vfprintf()> is C-specific, see L<perlfunc/printf> instead.
37120919 2154
41cd218c 2155=item C<vprintf>
37120919 2156
4d0de388 2157Not implemented. C<vprintf()> is C-specific, see L<perlfunc/printf> instead.
37120919 2158
41cd218c 2159=item C<vsprintf>
37120919 2160
4d0de388 2161Not implemented. C<vsprintf()> is C-specific, see L<perlfunc/sprintf> instead.
37120919 2162
41cd218c 2163=item C<wait>
37120919 2164
4755096e
GS
2165This is identical to Perl's builtin C<wait()> function,
2166see L<perlfunc/wait>.
37120919 2167
41cd218c 2168=item C<waitpid>
37120919 2169
cb1a09d0 2170Wait for a child process to change state. This is identical to Perl's
4755096e 2171builtin C<waitpid()> function, see L<perlfunc/waitpid>.
cb1a09d0 2172
2ac1ef3d 2173 $pid = POSIX::waitpid( -1, POSIX::WNOHANG );
cb1a09d0 2174 print "status = ", ($? / 256), "\n";
37120919 2175
351ab2ad 2176See L</mblen>.
37120919 2177
41cd218c 2178=item C<wctomb>
37120919 2179
5a6637f0
KW
2180This is the same as the C function C<wctomb()> on unthreaded perls. On
2181threaded perls, it transparently (almost) substitutes the more
2182thread-safe L<C<wcrtomb>(3)>, if available, instead of C<wctomb>.
351ab2ad 2183
5a6637f0
KW
2184Core Perl does not have any support for wide and multibyte locales,
2185except Unicode UTF-8 locales. This function, in conjunction with
2186L</mblen> and L</mbtowc> may be used to roll your own decoding/encoding
2187of other types of multi-byte locales.
2188
2189Use C<undef> as the first parameter to this function to get the effect
2190of passing NULL as the first parameter to C<wctomb>. This resets any
2191shift state to its initial value. The return value is undefined if
2192C<wcrtomb> was substituted, so you should never rely on it.
2193
2194When the first parameter is a scalar, the code point contained in the
2195scalar second parameter is converted into a multi-byte string and stored
2196into the first parameter scalar. This is based on the locale that
2197currently underlies the program, regardless of whether or not the
2198function is called from Perl code that is within the scope of S<C<use
2199locale>>. The return value is the number of bytes stored; or negative
2200if the code point isn't representable in the current locale. Perl makes
2201no attempt at hiding from your code any differences in the C<errno>
2202setting between C<wctomb> and C<wcrtomb>. It does set C<errno> to 0
2203before calling them.
37120919 2204
41cd218c 2205=item C<write>
37120919 2206
cb1a09d0
AD
2207Write to a file. This uses file descriptors such as those obtained by
2208calling C<POSIX::open>.
2209
2210 $fd = POSIX::open( "foo", &POSIX::O_WRONLY );
2211 $buf = "hello";
a0604b4c 2212 $bytes = POSIX::write( $fd, $buf, 5 );
37120919
AD
2213
2214Returns C<undef> on failure.
2215
4755096e
GS
2216See also L<perlfunc/syswrite>.
2217
37120919
AD
2218=back
2219
2220=head1 CLASSES
2221
41cd218c 2222=head2 C<POSIX::SigAction>
37120919
AD
2223
2224=over 8
2225
41cd218c 2226=item C<new>
37120919 2227
cb1a09d0 2228Creates a new C<POSIX::SigAction> object which corresponds to the C
3609ea0d
JH
2229C<struct sigaction>. This object will be destroyed automatically when
2230it is no longer needed. The first parameter is the handler, a sub
2231reference. The second parameter is a C<POSIX::SigSet> object, it
2232defaults to the empty set. The third parameter contains the
28757baa 2233C<sa_flags>, it defaults to 0.
cb1a09d0 2234
28757baa 2235 $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
b70c169c
FC
2236 $sigaction = POSIX::SigAction->new(
2237 \&handler, $sigset, &POSIX::SA_NOCLDSTOP
2238 );
cb1a09d0 2239
d36b6582 2240This C<POSIX::SigAction> object is intended for use with the C<POSIX::sigaction()>
cb1a09d0 2241function.
37120919
AD
2242
2243=back
2244
557c0de7
BD
2245=over 8
2246
41cd218c 2247=item C<handler>
557c0de7 2248
41cd218c 2249=item C<mask>
557c0de7 2250
41cd218c 2251=item C<flags>
557c0de7
BD
2252
2253accessor functions to get/set the values of a SigAction object.
2254
2255 $sigset = $sigaction->mask;
2256 $sigaction->flags(&POSIX::SA_RESTART);
2257
41cd218c 2258=item C<safe>
d36b6582
CS
2259
2260accessor function for the "safe signals" flag of a SigAction object; see
2261L<perlipc> for general information on safe (a.k.a. "deferred") signals. If
2262you wish to handle a signal safely, use this accessor to set the "safe" flag
2263in the C<POSIX::SigAction> object:
2264
2265 $sigaction->safe(1);
2266
2267You may also examine the "safe" flag on the output action object which is
2268filled in when given as the third parameter to C<POSIX::sigaction()>:
2269
2270 sigaction(SIGINT, $new_action, $old_action);
2271 if ($old_action->safe) {
2272 # previous SIGINT handler used safe signals
2273 }
2274
557c0de7
BD
2275=back
2276
41cd218c 2277=head2 C<POSIX::SigRt>
3609ea0d
JH
2278
2279=over 8
2280
41cd218c 2281=item C<%SIGRT>
3609ea0d
JH
2282
2283A hash of the POSIX realtime signal handlers. It is an extension of
41cd218c
KW
2284the standard C<%SIG>, the C<$POSIX::SIGRT{SIGRTMIN}> is roughly equivalent
2285to C<$SIG{SIGRTMIN}>, but the right POSIX moves (see below) are made with
2286the C<POSIX::SigSet> and C<POSIX::sigaction> instead of accessing the C<%SIG>.
3609ea0d 2287
41cd218c 2288You can set the C<%POSIX::SIGRT> elements to set the POSIX realtime
3609ea0d
JH
2289signal handlers, use C<delete> and C<exists> on the elements, and use
2290C<scalar> on the C<%POSIX::SIGRT> to find out how many POSIX realtime
41cd218c 2291signals there are available S<C<(SIGRTMAX - SIGRTMIN + 1>>, the C<SIGRTMAX> is
3609ea0d
JH
2292a valid POSIX realtime signal).
2293
41cd218c 2294Setting the C<%SIGRT> elements is equivalent to calling this:
3609ea0d
JH
2295
2296 sub new {
2297 my ($rtsig, $handler, $flags) = @_;
b8921b3e 2298 my $sigset = POSIX::SigSet($rtsig);
b70c169c 2299 my $sigact = POSIX::SigAction->new($handler,$sigset,$flags);
3609ea0d
JH
2300 sigaction($rtsig, $sigact);
2301 }
2302
2303The flags default to zero, if you want something different you can
41cd218c 2304either use C<local> on C<$POSIX::SigRt::SIGACTION_FLAGS>, or you can
3609ea0d 2305derive from POSIX::SigRt and define your own C<new()> (the tied hash
41cd218c
KW
2306STORE method of the C<%SIGRT> calls C<new($rtsig, $handler, $SIGACTION_FLAGS)>,
2307where the C<$rtsig> ranges from zero to S<C<SIGRTMAX - SIGRTMIN + 1)>>.
3609ea0d 2308
41cd218c 2309Just as with any signal, you can use C<sigaction($rtsig, undef, $oa)> to
3609ea0d
JH
2310retrieve the installed signal handler (or, rather, the signal action).
2311
2312B<NOTE:> whether POSIX realtime signals really work in your system, or
2313whether Perl has been compiled so that it works with them, is outside
2314of this discussion.
2315
41cd218c 2316=item C<SIGRTMIN>
3609ea0d
JH
2317
2318Return the minimum POSIX realtime signal number available, or C<undef>
2319if no POSIX realtime signals are available.
2320
41cd218c 2321=item C<SIGRTMAX>
3609ea0d
JH
2322
2323Return the maximum POSIX realtime signal number available, or C<undef>
2324if no POSIX realtime signals are available.
2325
2326=back
2327
41cd218c 2328=head2 C<POSIX::SigSet>
37120919
AD
2329
2330=over 8
2331
41cd218c 2332=item C<new>
37120919
AD
2333
2334Create a new SigSet object. This object will be destroyed automatically
2335when it is no longer needed. Arguments may be supplied to initialize the
2336set.
2337
2338Create an empty set.
2339
2340 $sigset = POSIX::SigSet->new;
2341
41cd218c 2342Create a set with C<SIGUSR1>.
37120919
AD
2343
2344 $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
2345
3a5c73f3
TC
2346Throws an error if any of the signals supplied cannot be added to the
2347set.
2348
41cd218c 2349=item C<addset>
37120919
AD
2350
2351Add a signal to a SigSet object.
2352
2353 $sigset->addset( &POSIX::SIGUSR2 );
2354
2355Returns C<undef> on failure.
2356
41cd218c 2357=item C<delset>
37120919
AD
2358
2359Remove a signal from the SigSet object.
2360
2361 $sigset->delset( &POSIX::SIGUSR2 );
2362
2363Returns C<undef> on failure.
2364
41cd218c 2365=item C<emptyset>
37120919
AD
2366
2367Initialize the SigSet object to be empty.
2368
2369 $sigset->emptyset();
2370
2371Returns C<undef> on failure.
2372
41cd218c 2373=item C<fillset>
37120919
AD
2374
2375Initialize the SigSet object to include all signals.
2376
2377 $sigset->fillset();
2378
2379Returns C<undef> on failure.
2380
41cd218c 2381=item C<ismember>
37120919
AD
2382
2383Tests the SigSet object to see if it contains a specific signal.
2384
2385 if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
2386 print "contains SIGUSR1\n";
2387 }
2388
2389=back
2390
41cd218c 2391=head2 C<POSIX::Termios>
37120919
AD
2392
2393=over 8
2394
41cd218c 2395=item C<new>
37120919
AD
2396
2397Create a new Termios object. This object will be destroyed automatically
4d0de388 2398when it is no longer needed. A Termios object corresponds to the C<termios>
41cd218c
KW
2399C struct. C<new()> mallocs a new one, C<getattr()> fills it from a file descriptor,
2400and C<setattr()> sets a file descriptor's parameters to match Termios' contents.
37120919
AD
2401
2402 $termios = POSIX::Termios->new;
2403
41cd218c 2404=item C<getattr>
37120919 2405
cb1a09d0
AD
2406Get terminal control attributes.
2407
4d0de388 2408Obtain the attributes for C<stdin>.
cb1a09d0 2409
220f811a 2410 $termios->getattr( 0 ) # Recommended for clarity.
cb1a09d0
AD
2411 $termios->getattr()
2412
2413Obtain the attributes for stdout.
2414
2415 $termios->getattr( 1 )
37120919
AD
2416
2417Returns C<undef> on failure.
2418
41cd218c 2419=item C<getcc>
37120919 2420
4d0de388 2421Retrieve a value from the C<c_cc> field of a C<termios> object. The C<c_cc> field is
37120919
AD
2422an array so an index must be specified.
2423
2424 $c_cc[1] = $termios->getcc(1);
2425
41cd218c 2426=item C<getcflag>
37120919 2427
4d0de388 2428Retrieve the C<c_cflag> field of a C<termios> object.
37120919
AD
2429
2430 $c_cflag = $termios->getcflag;
2431
41cd218c 2432=item C<getiflag>
37120919 2433
4d0de388 2434Retrieve the C<c_iflag> field of a C<termios> object.
37120919
AD
2435
2436 $c_iflag = $termios->getiflag;
2437
41cd218c 2438=item C<getispeed>
37120919
AD
2439
2440Retrieve the input baud rate.
2441
2442 $ispeed = $termios->getispeed;
2443
41cd218c 2444=item C<getlflag>
37120919 2445
4d0de388 2446Retrieve the C<c_lflag> field of a C<termios> object.
37120919
AD
2447
2448 $c_lflag = $termios->getlflag;
2449
41cd218c 2450=item C<getoflag>
37120919 2451
4d0de388 2452Retrieve the C<c_oflag> field of a C<termios> object.
37120919
AD
2453
2454 $c_oflag = $termios->getoflag;
2455
41cd218c 2456=item C<getospeed>
37120919
AD
2457
2458Retrieve the output baud rate.
2459
2460 $ospeed = $termios->getospeed;
2461
41cd218c 2462=item C<setattr>
37120919 2463
cb1a09d0
AD
2464Set terminal control attributes.
2465
2466Set attributes immediately for stdout.
2467
2468 $termios->setattr( 1, &POSIX::TCSANOW );
37120919
AD
2469
2470Returns C<undef> on failure.
2471
41cd218c 2472=item C<setcc>
37120919 2473
4d0de388 2474Set a value in the C<c_cc> field of a C<termios> object. The C<c_cc> field is an
37120919
AD
2475array so an index must be specified.
2476
6b7a6f50 2477 $termios->setcc( &POSIX::VEOF, 1 );
37120919 2478
41cd218c 2479=item C<setcflag>
37120919 2480
4d0de388 2481Set the C<c_cflag> field of a C<termios> object.
37120919 2482
55d729e4 2483 $termios->setcflag( $c_cflag | &POSIX::CLOCAL );
37120919 2484
41cd218c 2485=item C<setiflag>
37120919 2486
4d0de388 2487Set the C<c_iflag> field of a C<termios> object.
37120919 2488
55d729e4 2489 $termios->setiflag( $c_iflag | &POSIX::BRKINT );
37120919 2490
41cd218c 2491=item C<setispeed>
37120919
AD
2492
2493Set the input baud rate.
2494
2495 $termios->setispeed( &POSIX::B9600 );
2496
2497Returns C<undef> on failure.
2498
41cd218c 2499=item C<setlflag>
37120919 2500
4d0de388 2501Set the C<c_lflag> field of a C<termios> object.
37120919 2502
55d729e4 2503 $termios->setlflag( $c_lflag | &POSIX::ECHO );
37120919 2504
41cd218c 2505=item C<setoflag>
37120919 2506
4d0de388 2507Set the C<c_oflag> field of a C<termios> object.
37120919 2508
55d729e4 2509 $termios->setoflag( $c_oflag | &POSIX::OPOST );
37120919 2510
41cd218c 2511=item C<setospeed>
37120919
AD
2512
2513Set the output baud rate.
2514
2515 $termios->setospeed( &POSIX::B9600 );
2516
2517Returns C<undef> on failure.
2518
2519=item Baud rate values
2520
41cd218c 2521C<B38400> C<B75> C<B200> C<B134> C<B300> C<B1800> C<B150> C<B0> C<B19200> C<B1200> C<B9600> C<B600> C<B4800> C<B50> C<B2400> C<B110>
37120919
AD
2522
2523=item Terminal interface values
2524
41cd218c 2525C<TCSADRAIN> C<TCSANOW> C<TCOON> C<TCIOFLUSH> C<TCOFLUSH> C<TCION> C<TCIFLUSH> C<TCSAFLUSH> C<TCIOFF> C<TCOOFF>
37120919 2526
41cd218c 2527=item C<c_cc> field values
37120919 2528
41cd218c 2529C<VEOF> C<VEOL> C<VERASE> C<VINTR> C<VKILL> C<VQUIT> C<VSUSP> C<VSTART> C<VSTOP> C<VMIN> C<VTIME> C<NCCS>
37120919 2530
41cd218c 2531=item C<c_cflag> field values
37120919 2532
41cd218c 2533C<CLOCAL> C<CREAD> C<CSIZE> C<CS5> C<CS6> C<CS7> C<CS8> C<CSTOPB> C<HUPCL> C<PARENB> C<PARODD>
37120919 2534
41cd218c 2535=item C<c_iflag> field values
37120919 2536
41cd218c 2537C<BRKINT> C<ICRNL> C<IGNBRK> C<IGNCR> C<IGNPAR> C<INLCR> C<INPCK> C<ISTRIP> C<IXOFF> C<IXON> C<PARMRK>
37120919 2538
41cd218c 2539=item C<c_lflag> field values
37120919 2540
41cd218c 2541C<ECHO> C<ECHOE> C<ECHOK> C<ECHONL> C<ICANON> C<IEXTEN> C<ISIG> C<NOFLSH> C<TOSTOP>
37120919 2542
41cd218c 2543=item C<c_oflag> field values
37120919 2544
41cd218c 2545C<OPOST>
37120919
AD
2546
2547=back
2548
2549=head1 PATHNAME CONSTANTS
2550
2551=over 8
2552
2553=item Constants
2554
41cd218c
KW
2555C<_PC_CHOWN_RESTRICTED> C<_PC_LINK_MAX> C<_PC_MAX_CANON> C<_PC_MAX_INPUT> C<_PC_NAME_MAX>
2556C<_PC_NO_TRUNC> C<_PC_PATH_MAX> C<_PC_PIPE_BUF> C<_PC_VDISABLE>
37120919
AD
2557
2558=back
2559
2560=head1 POSIX CONSTANTS
2561
2562=over 8
2563
2564=item Constants
2565
41cd218c
KW
2566C<_POSIX_ARG_MAX> C<_POSIX_CHILD_MAX> C<_POSIX_CHOWN_RESTRICTED> C<_POSIX_JOB_CONTROL>
2567C<_POSIX_LINK_MAX> C<_POSIX_MAX_CANON> C<_POSIX_MAX_INPUT> C<_POSIX_NAME_MAX>
2568C<_POSIX_NGROUPS_MAX> C<_POSIX_NO_TRUNC> C<_POSIX_OPEN_MAX> C<_POSIX_PATH_MAX>
2569C<_POSIX_PIPE_BUF> C<_POSIX_SAVED_IDS> C<_POSIX_SSIZE_MAX> C<_POSIX_STREAM_MAX>
2570C<_POSIX_TZNAME_MAX> C<_POSIX_VDISABLE> C<_POSIX_VERSION>
37120919
AD
2571
2572=back
2573
4fd667a8
TC
2574=head1 RESOURCE CONSTANTS
2575
2576Imported with the C<:sys_resource_h> tag.
2577
2578=over 8
2579
2580=item Constants
2581
912a1e06
DB
2582Added in Perl v5.28:
2583
4fd667a8
TC
2584C<PRIO_PROCESS> C<PRIO_PGRP> C<PRIO_USER>
2585
2586=back
2587
37120919
AD
2588=head1 SYSTEM CONFIGURATION
2589
2590=over 8
2591
2592=item Constants
2593
41cd218c
KW
2594C<_SC_ARG_MAX> C<_SC_CHILD_MAX> C<_SC_CLK_TCK> C<_SC_JOB_CONTROL> C<_SC_NGROUPS_MAX>
2595C<_SC_OPEN_MAX> C<_SC_PAGESIZE> C<_SC_SAVED_IDS> C<_SC_STREAM_MAX> C<_SC_TZNAME_MAX>
2596C<_SC_VERSION>
37120919
AD
2597
2598=back
2599
2600=head1 ERRNO
2601
2602=over 8
2603
2604=item Constants
2605
41cd218c
KW
2606C<E2BIG> C<EACCES> C<EADDRINUSE> C<EADDRNOTAVAIL> C<EAFNOSUPPORT> C<EAGAIN> C<EALREADY> C<EBADF> C<EBADMSG>
2607C<EBUSY> C<ECANCELED> C<ECHILD> C<ECONNABORTED> C<ECONNREFUSED> C<ECONNRESET> C<EDEADLK> C<EDESTADDRREQ>
2608C<EDOM> C<EDQUOT> C<EEXIST> C<EFAULT> C<EFBIG> C<EHOSTDOWN> C<EHOSTUNREACH> C<EIDRM> C<EILSEQ> C<EINPROGRESS>
2609C<EINTR> C<EINVAL> C<EIO> C<EISCONN> C<EISDIR> C<ELOOP> C<EMFILE> C<EMLINK> C<EMSGSIZE> C<ENAMETOOLONG>
2610C<ENETDOWN> C<ENETRESET> C<ENETUNREACH> C<ENFILE> C<ENOBUFS> C<ENODATA> C<ENODEV> C<ENOENT> C<ENOEXEC>
2611C<ENOLCK> C<ENOLINK> C<ENOMEM> C<ENOMSG> C<ENOPROTOOPT> C<ENOSPC> C<ENOSR> C<ENOSTR> C<ENOSYS> C<ENOTBLK>
2612C<ENOTCONN> C<ENOTDIR> C<ENOTEMPTY> C<ENOTRECOVERABLE> C<ENOTSOCK> C<ENOTSUP> C<ENOTTY> C<ENXIO>
2613C<EOPNOTSUPP> C<EOTHER> C<EOVERFLOW> C<EOWNERDEAD> C<EPERM> C<EPFNOSUPPORT> C<EPIPE> C<EPROCLIM> C<EPROTO>
2614C<EPROTONOSUPPORT> C<EPROTOTYPE> C<ERANGE> C<EREMOTE> C<ERESTART> C<EROFS> C<ESHUTDOWN>
2615C<ESOCKTNOSUPPORT> C<ESPIPE> C<ESRCH> C<ESTALE> C<ETIME> C<ETIMEDOUT> C<ETOOMANYREFS> C<ETXTBSY> C<EUSERS>
2616C<EWOULDBLOCK> C<EXDEV>
37120919
AD
2617
2618=back
2619
2620=head1 FCNTL
2621
2622=over 8
2623
2624=item Constants
2625
41cd218c
KW
2626C<FD_CLOEXEC> C<F_DUPFD> C<F_GETFD> C<F_GETFL> C<F_GETLK> C<F_OK> C<F_RDLCK> C<F_SETFD> C<F_SETFL> C<F_SETLK>
2627C<F_SETLKW> C<F_UNLCK> C<F_WRLCK> C<O_ACCMODE> C<O_APPEND> C<O_CREAT> C<O_EXCL> C<O_NOCTTY> C<O_NONBLOCK>
2628C<O_RDONLY> C<O_RDWR> C<O_TRUNC> C<O_WRONLY>
37120919
AD
2629
2630=back
2631
2632=head1 FLOAT
2633
2634=over 8
2635
2636=item Constants
2637
41cd218c
KW
2638C<DBL_DIG> C<DBL_EPSILON> C<DBL_MANT_DIG> C<DBL_MAX> C<DBL_MAX_10_EXP> C<DBL_MAX_EXP> C<DBL_MIN>
2639C<DBL_MIN_10_EXP> C<DBL_MIN_EXP> C<FLT_DIG> C<FLT_EPSILON> C<FLT_MANT_DIG> C<FLT_MAX>
2640C<FLT_MAX_10_EXP> C<FLT_MAX_EXP> C<FLT_MIN> C<FLT_MIN_10_EXP> C<FLT_MIN_EXP> C<FLT_RADIX>
2641C<FLT_ROUNDS> C<LDBL_DIG> C<LDBL_EPSILON> C<LDBL_MANT_DIG> C<LDBL_MAX> C<LDBL_MAX_10_EXP>
2642C<LDBL_MAX_EXP> C<LDBL_MIN> C<LDBL_MIN_10_EXP> C<LDBL_MIN_EXP>
37120919
AD
2643
2644=back
2645
98ab3abf
AP
2646=head1 FLOATING-POINT ENVIRONMENT
2647
2648=over 8
2649
2650=item Constants
2651
2652C<FE_DOWNWARD> C<FE_TONEAREST> C<FE_TOWARDZERO> C<FE_UPWARD>
2653on systems that support them.
2654
2655=back
2656
37120919
AD
2657=head1 LIMITS
2658
2659=over 8
2660
2661=item Constants
2662
41cd218c
KW
2663C<ARG_MAX> C<CHAR_BIT> C<CHAR_MAX> C<CHAR_MIN> C<CHILD_MAX> C<INT_MAX> C<INT_MIN> C<LINK_MAX> C<LONG_MAX>
2664C<LONG_MIN> C<MAX_CANON> C<MAX_INPUT> C<MB_LEN_MAX> C<NAME_MAX> C<NGROUPS_MAX> C<OPEN_MAX> C<PATH_MAX>
2665C<PIPE_BUF> C<SCHAR_MAX> C<SCHAR_MIN> C<SHRT_MAX> C<SHRT_MIN> C<SSIZE_MAX> C<STREAM_MAX> C<TZNAME_MAX>
2666C<UCHAR_MAX> C<UINT_MAX> C<ULONG_MAX> C<USHRT_MAX>
37120919
AD
2667
2668=back
2669
2670=head1 LOCALE
2671
2672=over 8
2673
2674=item Constants
2675
4d0de388
KW
2676C<LC_ALL> C<LC_COLLATE> C<LC_CTYPE> C<LC_MONETARY> C<LC_NUMERIC> C<LC_TIME> C<LC_MESSAGES>
2677on systems that support them.
37120919
AD
2678
2679=back
2680
2681=head1 MATH
2682
2683=over 8
2684
2685=item Constants
2686
41cd218c 2687C<HUGE_VAL>
37120919 2688
912a1e06
DB
2689Added in Perl v5.22:
2690
98ab3abf
AP
2691C<FP_ILOGB0> C<FP_ILOGBNAN> C<FP_INFINITE> C<FP_NAN> C<FP_NORMAL> C<FP_SUBNORMAL> C<FP_ZERO>
2692C<INFINITY> C<NAN> C<Inf> C<NaN>
2693C<M_1_PI> C<M_2_PI> C<M_2_SQRTPI> C<M_E> C<M_LN10> C<M_LN2> C<M_LOG10E> C<M_LOG2E> C<M_PI>
2694C<M_PI_2> C<M_PI_4> C<M_SQRT1_2> C<M_SQRT2>
2695on systems with C99 support.
2696
37120919
AD
2697=back
2698
2699=head1 SIGNAL
2700
2701=over 8
2702
2703=item Constants
2704
41cd218c
KW
2705C<SA_NOCLDSTOP> C<SA_NOCLDWAIT> C<SA_NODEFER> C<SA_ONSTACK> C<SA_RESETHAND> C<SA_RESTART>
2706C<SA_SIGINFO> C<SIGABRT> C<SIGALRM> C<SIGCHLD> C<SIGCONT> C<SIGFPE> C<SIGHUP> C<SIGILL> C<SIGINT>
2707C<SIGKILL> C<SIGPIPE> C<SIGQUIT> C<SIGSEGV> C<SIGSTOP> C<SIGTERM> C<SIGTSTP> C<SIGTTIN> C<SIGTTOU>
2708C<SIGUSR1> C<SIGUSR2> C<SIG_BLOCK> C<SIG_DFL> C<SIG_ERR> C<SIG_IGN> C<SIG_SETMASK>
2709C<SIG_UNBLOCK>
912a1e06
DB
2710
2711Added in Perl v5.24:
2712
34e79b75
DIM
2713C<ILL_ILLOPC> C<ILL_ILLOPN> C<ILL_ILLADR> C<ILL_ILLTRP> C<ILL_PRVOPC> C<ILL_PRVREG> C<ILL_COPROC>
2714C<ILL_BADSTK> C<FPE_INTDIV> C<FPE_INTOVF> C<FPE_FLTDIV> C<FPE_FLTOVF> C<FPE_FLTUND> C<FPE_FLTRES>
2715C<FPE_FLTINV> C<FPE_FLTSUB> C<SEGV_MAPERR> C<SEGV_ACCERR> C<BUS_ADRALN> C<BUS_ADRERR>
2716C<BUS_OBJERR> C<TRAP_BRKPT> C<TRAP_TRACE> C<CLD_EXITED> C<CLD_KILLED> C<CLD_DUMPED> C<CLD_TRAPPED>
2717C<CLD_STOPPED> C<CLD_CONTINUED> C<POLL_IN> C<POLL_OUT> C<POLL_MSG> C<POLL_ERR> C<POLL_PRI>
2718C<POLL_HUP> C<SI_USER> C<SI_QUEUE> C<SI_TIMER> C<SI_ASYNCIO> C<SI_MESGQ>
37120919
AD
2719
2720=back
2721
2722=head1 STAT
2723
2724=over 8
2725
2726=item Constants
2727
41cd218c
KW
2728C<S_IRGRP> C<S_IROTH> C<S_IRUSR> C<S_IRWXG> C<S_IRWXO> C<S_IRWXU> C<S_ISGID> C<S_ISUID> C<S_IWGRP> C<S_IWOTH>
2729C<S_IWUSR> C<S_IXGRP> C<S_IXOTH> C<S_IXUSR>
37120919
AD
2730
2731=item Macros
2732
41cd218c 2733C<S_ISBLK> C<S_ISCHR> C<S_ISDIR> C<S_ISFIFO> C<S_ISREG>
37120919
AD
2734
2735=back
2736
2737=head1 STDLIB
2738
2739=over 8
2740
2741=item Constants
2742
41cd218c 2743C<EXIT_FAILURE> C<EXIT_SUCCESS> C<MB_CUR_MAX> C<RAND_MAX>
37120919
AD
2744
2745=back
2746
2747=head1 STDIO
2748
2749=over 8
2750
2751=item Constants
2752
1cb852db 2753C<BUFSIZ> C<EOF> C<FILENAME_MAX> C<L_ctermid> C<L_cuserid> C<TMP_MAX>
37120919
AD
2754
2755=back
2756
2757=head1 TIME
2758
2759=over 8
2760
2761=item Constants
2762
41cd218c 2763C<CLK_TCK> C<CLOCKS_PER_SEC>
37120919
AD
2764
2765=back
2766
2767=head1 UNISTD
2768
2769=over 8
2770
2771=item Constants
2772
41cd218c 2773C<R_OK> C<SEEK_CUR> C<SEEK_END> C<SEEK_SET> C<STDIN_FILENO> C<STDOUT_FILENO> C<STDERR_FILENO> C<W_OK> C<X_OK>
37120919
AD
2774
2775=back
2776
2777=head1 WAIT
2778
2779=over 8
2780
2781=item Constants
2782
41cd218c 2783C<WNOHANG> C<WUNTRACED>
37120919 2784
9d6eb86e
JH
2785=over 16
2786
41cd218c 2787=item C<WNOHANG>
9d6eb86e
JH
2788
2789Do not suspend the calling process until a child process
2790changes state but instead return immediately.
2791
41cd218c 2792=item C<WUNTRACED>
9d6eb86e
JH
2793
2794Catch stopped child processes.
2795
2796=back
2797
37120919
AD
2798=item Macros
2799
41cd218c 2800C<WIFEXITED> C<WEXITSTATUS> C<WIFSIGNALED> C<WTERMSIG> C<WIFSTOPPED> C<WSTOPSIG>
37120919 2801
9d6eb86e
JH
2802=over 16
2803
41cd218c 2804=item C<WIFEXITED>
9d6eb86e 2805
41cd218c 2806C<WIFEXITED(${^CHILD_ERROR_NATIVE})> returns true if the child process
12a72a5a 2807exited normally (C<exit()> or by falling off the end of C<main()>)
9d6eb86e 2808
41cd218c 2809=item C<WEXITSTATUS>
9d6eb86e 2810
41cd218c
KW
2811C<WEXITSTATUS(${^CHILD_ERROR_NATIVE})> returns the normal exit status of
2812the child process (only meaningful if C<WIFEXITED(${^CHILD_ERROR_NATIVE})>
12a72a5a 2813is true)
9d6eb86e 2814
41cd218c 2815=item C<WIFSIGNALED>
9d6eb86e 2816
41cd218c 2817C<WIFSIGNALED(${^CHILD_ERROR_NATIVE})> returns true if the child process
12a72a5a 2818terminated because of a signal
9d6eb86e 2819
41cd218c 2820=item C<WTERMSIG>
9d6eb86e 2821
41cd218c
KW
2822C<WTERMSIG(${^CHILD_ERROR_NATIVE})> returns the signal the child process
2823terminated for (only meaningful if
2824C<WIFSIGNALED(${^CHILD_ERROR_NATIVE})>
12a72a5a 2825is true)
9d6eb86e 2826
41cd218c 2827=item C<WIFSTOPPED>
9d6eb86e 2828
41cd218c 2829C<WIFSTOPPED(${^CHILD_ERROR_NATIVE})> returns true if the child process is
12a72a5a 2830currently stopped (can happen only if you specified the WUNTRACED flag
41cd218c 2831to C<waitpid()>)
9d6eb86e 2832
41cd218c 2833=item C<WSTOPSIG>
9d6eb86e 2834
41cd218c
KW
2835C<WSTOPSIG(${^CHILD_ERROR_NATIVE})> returns the signal the child process
2836was stopped for (only meaningful if
2837C<WIFSTOPPED(${^CHILD_ERROR_NATIVE})>
12a72a5a 2838is true)
9d6eb86e
JH
2839
2840=back
2841
37120919
AD
2842=back
2843
a28fff51
SH
2844=head1 WINSOCK
2845
2846(Windows only.)
2847
2848=over 8
2849
2850=item Constants
2851
912a1e06
DB
2852Added in Perl v5.24:
2853
a28fff51
SH
2854C<WSAEINTR> C<WSAEBADF> C<WSAEACCES> C<WSAEFAULT> C<WSAEINVAL> C<WSAEMFILE> C<WSAEWOULDBLOCK>
2855C<WSAEINPROGRESS> C<WSAEALREADY> C<WSAENOTSOCK> C<WSAEDESTADDRREQ> C<WSAEMSGSIZE>
2856C<WSAEPROTOTYPE> C<WSAENOPROTOOPT> C<WSAEPROTONOSUPPORT> C<WSAESOCKTNOSUPPORT>
2857C<WSAEOPNOTSUPP> C<WSAEPFNOSUPPORT> C<WSAEAFNOSUPPORT> C<WSAEADDRINUSE>
2858C<WSAEADDRNOTAVAIL> C<WSAENETDOWN> C<WSAENETUNREACH> C<WSAENETRESET> C<WSAECONNABORTED>
2859C<WSAECONNRESET> C<WSAENOBUFS> C<WSAEISCONN> C<WSAENOTCONN> C<WSAESHUTDOWN>
2860C<WSAETOOMANYREFS> C<WSAETIMEDOUT> C<WSAECONNREFUSED> C<WSAELOOP> C<WSAENAMETOOLONG>
2861C<WSAEHOSTDOWN> C<WSAEHOSTUNREACH> C<WSAENOTEMPTY> C<WSAEPROCLIM> C<WSAEUSERS>
2862C<WSAEDQUOT> C<WSAESTALE> C<WSAEREMOTE> C<WSAEDISCON> C<WSAENOMORE> C<WSAECANCELLED>
2863C<WSAEINVALIDPROCTABLE> C<WSAEINVALIDPROVIDER> C<WSAEPROVIDERFAILEDINIT>
2864C<WSAEREFUSED>
2865
2866=back
2867