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