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