This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
POSIX.pod: Add cautions about locale use
[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>.
aa2bc4d3
KW
942It should not be used in a threaded application unless it's certain that
943the underlying locale is C or POSIX. This is because it otherwise
944changes the locale, which globally affects all threads simultaneously.
cb1a09d0 945
4755096e 946Here is how to query the database for the B<de> (Deutsch or German) locale.
cb1a09d0 947
c4e34987
DP
948 my $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" );
949 print "Locale: \"$loc\"\n";
950 my $lconv = POSIX::localeconv();
951 foreach my $property (qw(
952 decimal_point
953 thousands_sep
954 grouping
955 int_curr_symbol
956 currency_symbol
957 mon_decimal_point
958 mon_thousands_sep
959 mon_grouping
960 positive_sign
961 negative_sign
962 int_frac_digits
963 frac_digits
964 p_cs_precedes
965 p_sep_by_space
966 n_cs_precedes
967 n_sep_by_space
968 p_sign_posn
969 n_sign_posn
b15c1b56
AF
970 int_p_cs_precedes
971 int_p_sep_by_space
972 int_n_cs_precedes
973 int_n_sep_by_space
974 int_p_sign_posn
975 int_n_sign_posn
c4e34987
DP
976 ))
977 {
b70c169c
FC
978 printf qq(%s: "%s",\n),
979 $property, $lconv->{$property};
c4e34987 980 }
37120919 981
4d0de388
KW
982The members whose names begin with C<int_p_> and C<int_n_> were added by
983POSIX.1-2008 and are only available on systems that support them.
b15c1b56 984
41cd218c 985=item C<localtime>
37120919 986
4755096e 987This is identical to Perl's builtin C<localtime()> function for
dc416353
JK
988converting seconds since the epoch to a date see L<perlfunc/localtime> except
989that C<POSIX::localtime()> must be provided an explicit value (rather than
bda53d3e 990relying on an implicit C<$_>):
dc416353 991
bda53d3e 992 @localtime = POSIX::localtime(time); # good
dc416353 993
bda53d3e 994 @localtime = localtime(); # good
dc416353 995
bda53d3e 996 @localtime = POSIX::localtime(); # throws exception
37120919 997
41cd218c 998=item C<log>
37120919 999
4755096e
GS
1000This is identical to Perl's builtin C<log()> function,
1001returning the natural (I<e>-based) logarithm of the numerical argument,
1002see L<perlfunc/log>.
37120919 1003
41cd218c 1004=item C<log10>
37120919 1005
4755096e
GS
1006This is identical to the C function C<log10()>,
1007returning the 10-base logarithm of the numerical argument.
1008You can also use
1009
1010 sub log10 { log($_[0]) / log(10) }
1011
1012or
1013
3609ea0d 1014 sub log10 { log($_[0]) / 2.30258509299405 }
4755096e
GS
1015
1016or
1017
1018 sub log10 { log($_[0]) * 0.434294481903252 }
37120919 1019
41cd218c 1020=item C<longjmp>
37120919 1021
4d0de388 1022Not implemented. C<longjmp()> is C-specific: use L<perlfunc/die> instead.
37120919 1023
41cd218c 1024=item C<lseek>
37120919 1025
8903cb82 1026Move the file's read/write position. This uses file descriptors such as
cb1a09d0
AD
1027those obtained by calling C<POSIX::open>.
1028
1029 $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
1030 $off_t = POSIX::lseek( $fd, 0, &POSIX::SEEK_SET );
37120919
AD
1031
1032Returns C<undef> on failure.
1033
9d233e12
JH
1034=item C<lrint>
1035
351ab2ad
JH
1036Depending on the current floating point rounding mode, rounds the
1037argument either toward nearest (like L</round>), toward zero (like
1038L</trunc>), downward (toward negative infinity), or upward (toward
1039positive infinity) [C99].
9d233e12 1040
351ab2ad 1041For the rounding mode, see L</fegetround>.
9d233e12 1042
9e010b89
JH
1043=item C<lround>
1044
1045Like L</round>, but as integer, as opposed to floating point [C99].
1046
1047See also L</ceil>, L</floor>, L</trunc>.
1048
25a9f0e7
AC
1049Owing to an oversight, this is not currently exported by default, or as part of
1050the C<:math_h_c99> export tag; importing it must therefore be done by explicit
abc9e18b 1051name.
25a9f0e7 1052
41cd218c 1053=item C<malloc>
37120919 1054
4d0de388 1055Not implemented. C<malloc()> is C-specific. Perl does memory management transparently.
37120919 1056
41cd218c 1057=item C<mblen>
37120919 1058
cb1a09d0 1059This is identical to the C function C<mblen()>.
351ab2ad
JH
1060
1061Core Perl does not have any support for the wide and multibyte
4d0de388
KW
1062characters of the C standards, except under UTF-8 locales, so this might
1063be a rather useless function.
351ab2ad
JH
1064
1065However, Perl supports Unicode, see L<perluniintro>.
37120919 1066
41cd218c 1067=item C<mbstowcs>
37120919 1068
cb1a09d0 1069This is identical to the C function C<mbstowcs()>.
351ab2ad
JH
1070
1071See L</mblen>.
37120919 1072
41cd218c 1073=item C<mbtowc>
37120919 1074
cb1a09d0 1075This is identical to the C function C<mbtowc()>.
351ab2ad
JH
1076
1077See L</mblen>.
37120919 1078
41cd218c 1079=item C<memchr>
37120919 1080
4d0de388 1081Not implemented. C<memchr()> is C-specific, see L<perlfunc/index> instead.
37120919 1082
41cd218c 1083=item C<memcmp>
37120919 1084
4d0de388 1085Not implemented. C<memcmp()> is C-specific, use C<eq> instead, see L<perlop>.
37120919 1086
41cd218c 1087=item C<memcpy>
37120919 1088
4d0de388 1089Not implemented. C<memcpy()> is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
37120919 1090
41cd218c 1091=item C<memmove>
37120919 1092
4d0de388 1093Not implemented. C<memmove()> is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>.
37120919 1094
41cd218c 1095=item C<memset>
37120919 1096
4d0de388 1097Not implemented. C<memset()> is C-specific, use C<x> instead, see L<perlop>.
37120919 1098
41cd218c 1099=item C<mkdir>
37120919 1100
4755096e
GS
1101This is identical to Perl's builtin C<mkdir()> function
1102for creating directories, see L<perlfunc/mkdir>.
37120919 1103
41cd218c 1104=item C<mkfifo>
37120919 1105
4755096e
GS
1106This is similar to the C function C<mkfifo()> for creating
1107FIFO special files.
37120919 1108
4755096e
GS
1109 if (mkfifo($path, $mode)) { ....
1110
1111Returns C<undef> on failure. The C<$mode> is similar to the
220f811a
JH
1112mode of C<mkdir()>, see L<perlfunc/mkdir>, though for C<mkfifo>
1113you B<must> specify the C<$mode>.
37120919 1114
41cd218c 1115=item C<mktime>
37120919 1116
cb1a09d0
AD
1117Convert date/time info to a calendar time.
1118
1119Synopsis:
1120
b70c169c
FC
1121 mktime(sec, min, hour, mday, mon, year, wday = 0,
1122 yday = 0, isdst = -1)
cb1a09d0 1123
4d0de388
KW
1124The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero,
1125I<i.e.>, January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
1126year (C<year>) is given in years since 1900; I<i.e.>, the year 1995 is 95; the
cb1a09d0
AD
1127year 2001 is 101. Consult your system's C<mktime()> manpage for details
1128about these and the other arguments.
1129
1130Calendar time for December 12, 1995, at 10:30 am.
1131
1132 $time_t = POSIX::mktime( 0, 30, 10, 12, 11, 95 );
1133 print "Date = ", POSIX::ctime($time_t);
37120919
AD
1134
1135Returns C<undef> on failure.
1136
41cd218c 1137=item C<modf>
37120919 1138
cb1a09d0
AD
1139Return the integral and fractional parts of a floating-point number.
1140
1141 ($fractional, $integral) = POSIX::modf( 3.14 );
37120919 1142
351ab2ad
JH
1143See also L</round>.
1144
d7a0f0b0
JH
1145=item C<NaN>
1146
1147The not-a-number as a constant:
1148
1149 use POSIX qw(NaN);
1150 my $nan = NaN;
1151
1152See also L</nan>, C</isnan>, and L</fpclassify>.
1153
9d233e12
JH
1154=item C<nan>
1155
07bb61ac
JH
1156 my $nan = nan();
1157
1158Returns C<NaN>, not-a-number [C99].
1159
1160The returned NaN is always a I<quiet> NaN, as opposed to I<signaling>.
1161
1162With an argument, can be used to generate a NaN with I<payload>.
1163The argument is first interpreted as a floating point number,
1164but then any fractional parts are truncated (towards zero),
1165and the value is interpreted as an unsigned integer.
1166The bits of this integer are stored in the unused bits of the NaN.
1167
1168The result has a dual nature: it is a NaN, but it also carries
1169the integer inside it. The integer can be retrieved with L</getpayload>.
1170Note, though, that the payload is not propagated, not even on copies,
1171and definitely not in arithmetic operations.
1172
1173How many bits fit in the NaN depends on what kind of floating points
1174are being used, but on the most common platforms (64-bit IEEE 754,
1175or the x86 80-bit long doubles) there are 51 and 61 bits available,
1176respectively. (There would be 52 and 62, but the quiet/signaling
1177bit of NaNs takes away one.) However, because of the floating-point-to-
1178integer-and-back conversions, please test carefully whether you get back
1179what you put in. If your integers are only 32 bits wide, you probably
1180should not rely on more than 32 bits of payload.
9d233e12 1181
07bb61ac
JH
1182Whether a "signaling" NaN is in any way different from a "quiet" NaN,
1183depends on the platform. Also note that the payload of the default
1184NaN (no argument to nan()) is not necessarily zero, use C<setpayload>
8384a6d6
JH
1185to explicitly set the payload. On some platforms like the 32-bit x86,
1186(unless using the 80-bit long doubles) the signaling bit is not supported
1187at all.
07bb61ac 1188
d7a0f0b0 1189See also L</isnan>, L</NaN>, L</setpayload> and L</issignaling>.
351ab2ad 1190
9d233e12
JH
1191=item C<nearbyint>
1192
1193Returns the nearest integer to the argument, according to the current
1194rounding mode (see L</fegetround>) [C99].
1195
1196=item C<nextafter>
1197
4d0de388
KW
1198Returns the next representable floating point number after C<x> in the
1199direction of C<y> [C99].
1200
1201 my $nextafter = POSIX::nextafter($x, $y);
9d233e12
JH
1202
1203Like L</nexttoward>, but potentially less accurate.
1204
1205=item C<nexttoward>
1206
4d0de388
KW
1207Returns the next representable floating point number after C<x> in the
1208direction of C<y> [C99].
1209
1210 my $nexttoward = POSIX::nexttoward($x, $y);
9d233e12
JH
1211
1212Like L</nextafter>, but potentially more accurate.
1213
41cd218c 1214=item C<nice>
37120919 1215
4755096e
GS
1216This is similar to the C function C<nice()>, for changing
1217the scheduling preference of the current process. Positive
4d0de388
KW
1218arguments mean a more polite process, negative values a more
1219needy process. Normal (non-root) user processes can only change towards
1220being more polite.
37120919
AD
1221
1222Returns C<undef> on failure.
1223
41cd218c 1224=item C<offsetof>
37120919 1225
4d0de388 1226Not implemented. C<offsetof()> is C-specific, you probably want to see L<perlfunc/pack> instead.
37120919 1227
41cd218c 1228=item C<open>
37120919 1229
cb1a09d0
AD
1230Open a file for reading for writing. This returns file descriptors, not
1231Perl filehandles. Use C<POSIX::close> to close the file.
1232
1233Open a file read-only with mode 0666.
1234
1235 $fd = POSIX::open( "foo" );
1236
1237Open a file for read and write.
1238
1239 $fd = POSIX::open( "foo", &POSIX::O_RDWR );
1240
1241Open a file for write, with truncation.
1242
b70c169c
FC
1243 $fd = POSIX::open(
1244 "foo", &POSIX::O_WRONLY | &POSIX::O_TRUNC
1245 );
cb1a09d0
AD
1246
1247Create a new file with mode 0640. Set up the file for writing.
1248
b70c169c
FC
1249 $fd = POSIX::open(
1250 "foo", &POSIX::O_CREAT | &POSIX::O_WRONLY, 0640
1251 );
37120919
AD
1252
1253Returns C<undef> on failure.
1254
4755096e
GS
1255See also L<perlfunc/sysopen>.
1256
41cd218c 1257=item C<opendir>
37120919 1258
cb1a09d0
AD
1259Open a directory for reading.
1260
2359510d 1261 $dir = POSIX::opendir( "/var" );
cb1a09d0
AD
1262 @files = POSIX::readdir( $dir );
1263 POSIX::closedir( $dir );
1264
1265Returns C<undef> on failure.
37120919 1266
41cd218c 1267=item C<pathconf>
37120919
AD
1268
1269Retrieves the value of a configurable limit on a file or directory.
1270
1271The following will determine the maximum length of the longest allowable
2359510d 1272pathname on the filesystem which holds C</var>.
37120919 1273
b70c169c
FC
1274 $path_max = POSIX::pathconf( "/var",
1275 &POSIX::_PC_PATH_MAX );
37120919
AD
1276
1277Returns C<undef> on failure.
1278
41cd218c 1279=item C<pause>
37120919 1280
4755096e
GS
1281This is similar to the C function C<pause()>, which suspends
1282the execution of the current process until a signal is received.
37120919
AD
1283
1284Returns C<undef> on failure.
1285
41cd218c 1286=item C<perror>
37120919 1287
4755096e 1288This is identical to the C function C<perror()>, which outputs to the
41cd218c 1289standard error stream the specified message followed by C<": "> and the
4755096e
GS
1290current error string. Use the C<warn()> function and the C<$!>
1291variable instead, see L<perlfunc/warn> and L<perlvar/$ERRNO>.
37120919 1292
41cd218c 1293=item C<pipe>
37120919 1294
cb1a09d0
AD
1295Create an interprocess channel. This returns file descriptors like those
1296returned by C<POSIX::open>.
1297
b27d06da
MS
1298 my ($read, $write) = POSIX::pipe();
1299 POSIX::write( $write, "hello", 5 );
1300 POSIX::read( $read, $buf, 5 );
37120919 1301
4755096e
GS
1302See also L<perlfunc/pipe>.
1303
41cd218c 1304=item C<pow>
37120919 1305
4755096e 1306Computes C<$x> raised to the power C<$exponent>.
37120919
AD
1307
1308 $ret = POSIX::pow( $x, $exponent );
1309
4755096e
GS
1310You can also use the C<**> operator, see L<perlop>.
1311
41cd218c 1312=item C<printf>
37120919 1313
4d0de388 1314Formats and prints the specified arguments to C<STDOUT>.
4755096e 1315See also L<perlfunc/printf>.
37120919 1316
41cd218c 1317=item C<putc>
37120919 1318
4d0de388 1319Not implemented. C<putc()> is C-specific, see L<perlfunc/print> instead.
37120919 1320
41cd218c 1321=item C<putchar>
37120919 1322
4d0de388 1323Not implemented. C<putchar()> is C-specific, see L<perlfunc/print> instead.
37120919 1324
41cd218c 1325=item C<puts>
37120919 1326
4d0de388 1327Not implemented. C<puts()> is C-specific, see L<perlfunc/print> instead.
37120919 1328
41cd218c 1329=item C<qsort>
37120919 1330
4d0de388 1331Not implemented. C<qsort()> is C-specific, see L<perlfunc/sort> instead.
37120919 1332
41cd218c 1333=item C<raise>
37120919
AD
1334
1335Sends the specified signal to the current process.
4755096e 1336See also L<perlfunc/kill> and the C<$$> in L<perlvar/$PID>.
37120919 1337
41cd218c 1338=item C<rand>
37120919 1339
4d0de388 1340Not implemented. C<rand()> is non-portable, see L<perlfunc/rand> instead.
37120919 1341
41cd218c 1342=item C<read>
37120919 1343
cb1a09d0
AD
1344Read from a file. This uses file descriptors such as those obtained by
1345calling C<POSIX::open>. If the buffer C<$buf> is not large enough for the
1346read then Perl will extend it to make room for the request.
1347
1348 $fd = POSIX::open( "foo", &POSIX::O_RDONLY );
1349 $bytes = POSIX::read( $fd, $buf, 3 );
37120919
AD
1350
1351Returns C<undef> on failure.
1352
4755096e
GS
1353See also L<perlfunc/sysread>.
1354
41cd218c 1355=item C<readdir>
37120919 1356
4755096e
GS
1357This is identical to Perl's builtin C<readdir()> function
1358for reading directory entries, see L<perlfunc/readdir>.
37120919 1359
41cd218c 1360=item C<realloc>
37120919 1361
4d0de388 1362Not implemented. C<realloc()> is C-specific. Perl does memory management transparently.
37120919 1363
9d233e12
JH
1364=item C<remainder>
1365
4d0de388 1366Given C<x> and C<y>, returns the value S<C<x - n*y>>, where C<n> is the integer
56966515 1367closest to C<x>/C<y>. [C99]
4d0de388
KW
1368
1369 my $remainder = POSIX::remainder($x, $y)
9d233e12
JH
1370
1371See also L</remquo>.
1372
41cd218c 1373=item C<remove>
37120919 1374
4755096e
GS
1375This is identical to Perl's builtin C<unlink()> function
1376for removing files, see L<perlfunc/unlink>.
37120919 1377
9d233e12
JH
1378=item C<remquo>
1379
1380Like L</remainder> but also returns the low-order bits of the quotient (n)
1381[C99]
1382
1383(This is quite esoteric interface, mainly used to implement numerical
1384algorithms.)
1385
41cd218c 1386=item C<rename>
37120919 1387
4755096e
GS
1388This is identical to Perl's builtin C<rename()> function
1389for renaming files, see L<perlfunc/rename>.
37120919 1390
41cd218c 1391=item C<rewind>
37120919
AD
1392
1393Seeks to the beginning of the file.
1394
41cd218c 1395=item C<rewinddir>
37120919 1396
4755096e
GS
1397This is identical to Perl's builtin C<rewinddir()> function for
1398rewinding directory entry streams, see L<perlfunc/rewinddir>.
37120919 1399
9d233e12
JH
1400=item C<rint>
1401
1402Identical to L</lrint>.
1403
41cd218c 1404=item C<rmdir>
37120919 1405
4755096e
GS
1406This is identical to Perl's builtin C<rmdir()> function
1407for removing (empty) directories, see L<perlfunc/rmdir>.
37120919 1408
9d233e12
JH
1409=item C<round>
1410
9e010b89
JH
1411Returns the integer (but still as floating point) nearest to the
1412argument [C99].
9d233e12 1413
351ab2ad 1414See also L</ceil>, L</floor>, L</lround>, L</modf>, and L</trunc>.
9d233e12
JH
1415
1416=item C<scalbn>
1417
4d0de388 1418Returns S<C<x * 2**y>> [C99].
9d233e12
JH
1419
1420See also L</frexp> and L</ldexp>.
1421
41cd218c 1422=item C<scanf>
37120919 1423
4d0de388 1424Not implemented. C<scanf()> is C-specific, use E<lt>E<gt> and regular expressions instead,
4755096e 1425see L<perlre>.
37120919 1426
41cd218c 1427=item C<setgid>
37120919 1428
a043a685
GW
1429Sets the real group identifier and the effective group identifier for
1430this process. Similar to assigning a value to the Perl's builtin
2bc0d022 1431C<$)> variable, see L<perlvar/$EGID>, except that the latter
a043a685
GW
1432will change only the real user identifier, and that the setgid()
1433uses only a single numeric argument, as opposed to a space-separated
1434list of numbers.
37120919 1435
41cd218c 1436=item C<setjmp>
37120919 1437
4d0de388 1438Not implemented. C<setjmp()> is C-specific: use C<eval {}> instead,
4755096e 1439see L<perlfunc/eval>.
37120919 1440
41cd218c 1441=item C<setlocale>
37120919 1442
fc82b82e
KW
1443WARNING! Do NOT use this function in a L<thread|threads>. The locale
1444will change in all other threads at the same time, and should your
1445thread get paused by the operating system, and another started, that
1446thread will not have the locale it is expecting. On some platforms,
1447there can be a race leading to segfaults if two threads call this
1448function nearly simultaneously.
1449
6ea81ccf 1450Modifies and queries the program's underlying locale. Users of this
dfcc8045
KW
1451function should read L<perllocale>, whch provides a comprehensive
1452discussion of Perl locale handling, knowledge of which is necessary to
1453properly use this function. It contains
1454L<a section devoted to this function|perllocale/The setlocale function>.
1455The discussion here is merely a summary reference for C<setlocale()>.
6ea81ccf
KW
1456Note that Perl itself is almost entirely unaffected by the locale
1457except within the scope of S<C<"use locale">>. (Exceptions are listed
d6ded950 1458in L<perllocale/Not within the scope of "use locale">.)
6ea81ccf
KW
1459
1460The following examples assume
c26abfa6
JH
1461
1462 use POSIX qw(setlocale LC_ALL LC_CTYPE);
1463
1464has been issued.
37120919 1465
8966fa01
JH
1466The following will set the traditional UNIX system locale behavior
1467(the second argument C<"C">).
37120919 1468
c26abfa6 1469 $loc = setlocale( LC_ALL, "C" );
37120919 1470
41cd218c 1471The following will query the current C<LC_CTYPE> category. (No second
c26abfa6 1472argument means 'query'.)
8966fa01 1473
c26abfa6 1474 $loc = setlocale( LC_CTYPE );
8966fa01 1475
41cd218c 1476The following will set the C<LC_CTYPE> behaviour according to the locale
8966fa01 1477environment variables (the second argument C<"">).
4c9b78f4 1478Please see your system's C<setlocale(3)> documentation for the locale
71be2cbc 1479environment variables' meaning or consult L<perllocale>.
8966fa01 1480
c26abfa6 1481 $loc = setlocale( LC_CTYPE, "" );
8966fa01 1482
41cd218c 1483The following will set the C<LC_COLLATE> behaviour to Argentinian
8966fa01 1484Spanish. B<NOTE>: The naming and availability of locales depends on
71be2cbc 1485your operating system. Please consult L<perllocale> for how to find
8966fa01
JH
1486out which locales are available in your system.
1487
801ed997 1488 $loc = setlocale( LC_COLLATE, "es_AR.ISO8859-1" );
8966fa01 1489
07bb61ac
JH
1490=item C<setpayload>
1491
1492 use POSIX ':nan_payload';
1493 setpayload($var, $payload);
1494
1495Sets the C<NaN> payload of var.
1496
1497NOTE: the NaN payload APIs are based on the latest (as of June 2015)
1498proposed ISO C interfaces, but they are not yet a standard. Things
1499may change.
1500
1501See L</nan> for more discussion about C<NaN>.
1502
1503See also L</setpayloadsig>, L</isnan>, L</getpayload>, and L</issignaling>.
1504
1505=item C<setpayloadsig>
1506
1507 use POSIX ':nan_payload';
1508 setpayloadsig($var, $payload);
1509
1510Like L</setpayload> but also makes the NaN I<signaling>.
1511
1512Depending on the platform the NaN may or may not behave differently.
1513
1514Note the API instability warning in L</setpayload>.
1515
1516Note that because how the floating point formats work out, on the most
1517common platforms signaling payload of zero is best avoided,
1518since it might end up being identical to C<+Inf>.
1519
1520See also L</nan>, L</isnan>, L</getpayload>, and L</issignaling>.
1521
41cd218c 1522=item C<setpgid>
37120919 1523
4755096e
GS
1524This is similar to the C function C<setpgid()> for
1525setting the process group identifier of the current process.
37120919
AD
1526
1527Returns C<undef> on failure.
1528
41cd218c 1529=item C<setsid>
37120919 1530
4755096e
GS
1531This is identical to the C function C<setsid()> for
1532setting the session identifier of the current process.
37120919 1533
41cd218c 1534=item C<setuid>
37120919 1535
a043a685
GW
1536Sets the real user identifier and the effective user identifier for
1537this process. Similar to assigning a value to the Perl's builtin
1538C<$E<lt>> variable, see L<perlvar/$UID>, except that the latter
1539will change only the real user identifier.
37120919 1540
41cd218c 1541=item C<sigaction>
37120919 1542
3609ea0d
JH
1543Detailed signal management. This uses C<POSIX::SigAction> objects for
1544the C<action> and C<oldaction> arguments (the oldaction can also be
1545just a hash reference). Consult your system's C<sigaction> manpage
1546for details, see also C<POSIX::SigRt>.
cb1a09d0
AD
1547
1548Synopsis:
1549
1d81eac9 1550 sigaction(signal, action, oldaction = 0)
37120919 1551
1d81eac9 1552Returns C<undef> on failure. The C<signal> must be a number (like
41cd218c 1553C<SIGHUP>), not a string (like C<"SIGHUP">), though Perl does try hard
1d81eac9 1554to understand you.
37120919 1555
41cd218c 1556If you use the C<SA_SIGINFO> flag, the signal handler will in addition to
8aad04aa
JH
1557the first argument, the signal name, also receive a second argument, a
1558hash reference, inside which are the following keys with the following
1559semantics, as defined by POSIX/SUSv3:
1560
1561 signo the signal number
1562 errno the error number
1563 code if this is zero or less, the signal was sent by
1564 a user process and the uid and pid make sense,
1565 otherwise the signal was sent by the kernel
79dec0f4 1566
34e79b75
DIM
1567The constants for specific C<code> values can be imported individually
1568or using the C<:signal_h_si_code> tag.
1569
79dec0f4
JH
1570The following are also defined by POSIX/SUSv3, but unfortunately
1571not very widely implemented:
1572
8aad04aa
JH
1573 pid the process id generating the signal
1574 uid the uid of the process id generating the signal
1575 status exit value or signal for SIGCHLD
1576 band band event for SIGPOLL
408b5f5e
KW
1577 addr address of faulting instruction or memory
1578 reference for SIGILL, SIGFPE, SIGSEGV or SIGBUS
8aad04aa
JH
1579
1580A third argument is also passed to the handler, which contains a copy
41cd218c
KW
1581of the raw binary contents of the C<siginfo> structure: if a system has
1582some non-POSIX fields, this third argument is where to C<unpack()> them
8aad04aa
JH
1583from.
1584
41cd218c 1585Note that not all C<siginfo> values make sense simultaneously (some are
8aad04aa
JH
1586valid only for certain signals, for example), and not all values make
1587sense from Perl perspective, you should to consult your system's
1588C<sigaction> and possibly also C<siginfo> documentation.
1589
41cd218c 1590=item C<siglongjmp>
37120919 1591
4d0de388 1592Not implemented. C<siglongjmp()> is C-specific: use L<perlfunc/die> instead.
37120919 1593
9d233e12
JH
1594=item C<signbit>
1595
1596Returns zero for positive arguments, non-zero for negative arguments [C99].
1597
41cd218c 1598=item C<sigpending>
37120919 1599
cb1a09d0
AD
1600Examine signals that are blocked and pending. This uses C<POSIX::SigSet>
1601objects for the C<sigset> argument. Consult your system's C<sigpending>
1602manpage for details.
1603
1604Synopsis:
1605
1606 sigpending(sigset)
37120919
AD
1607
1608Returns C<undef> on failure.
1609
41cd218c 1610=item C<sigprocmask>
37120919 1611
cb1a09d0
AD
1612Change and/or examine calling process's signal mask. This uses
1613C<POSIX::SigSet> objects for the C<sigset> and C<oldsigset> arguments.
1614Consult your system's C<sigprocmask> manpage for details.
1615
1616Synopsis:
1617
1618 sigprocmask(how, sigset, oldsigset = 0)
37120919
AD
1619
1620Returns C<undef> on failure.
1621
faaf6836
LT
1622Note that you can't reliably block or unblock a signal from its own signal
1623handler if you're using safe signals. Other signals can be blocked or unblocked
1624reliably.
1625
41cd218c 1626=item C<sigsetjmp>
37120919 1627
4d0de388 1628Not implemented. C<sigsetjmp()> is C-specific: use C<eval {}> instead,
4755096e 1629see L<perlfunc/eval>.
37120919 1630
41cd218c 1631=item C<sigsuspend>
37120919 1632
cb1a09d0
AD
1633Install a signal mask and suspend process until signal arrives. This uses
1634C<POSIX::SigSet> objects for the C<signal_mask> argument. Consult your
1635system's C<sigsuspend> manpage for details.
1636
1637Synopsis:
1638
1639 sigsuspend(signal_mask)
37120919
AD
1640
1641Returns C<undef> on failure.
1642
41cd218c 1643=item C<sin>
37120919 1644
4755096e
GS
1645This is identical to Perl's builtin C<sin()> function
1646for returning the sine of the numerical argument,
c2e66d9e 1647see L<perlfunc/sin>. See also L<Math::Trig>.
37120919 1648
41cd218c 1649=item C<sinh>
37120919 1650
4755096e
GS
1651This is identical to the C function C<sinh()>
1652for returning the hyperbolic sine of the numerical argument.
c2e66d9e 1653See also L<Math::Trig>.
37120919 1654
41cd218c 1655=item C<sleep>
37120919 1656
2ab27a20
A
1657This is functionally identical to Perl's builtin C<sleep()> function
1658for suspending the execution of the current for process for certain
3609ea0d 1659number of seconds, see L<perlfunc/sleep>. There is one significant
2bad225e 1660difference, however: C<POSIX::sleep()> returns the number of
2ab27a20
A
1661B<unslept> seconds, while the C<CORE::sleep()> returns the
1662number of slept seconds.
37120919 1663
41cd218c 1664=item C<sprintf>
37120919 1665
4755096e
GS
1666This is similar to Perl's builtin C<sprintf()> function
1667for returning a string that has the arguments formatted as requested,
1668see L<perlfunc/sprintf>.
37120919 1669
41cd218c 1670=item C<sqrt>
37120919
AD
1671
1672This is identical to Perl's builtin C<sqrt()> function.
4755096e
GS
1673for returning the square root of the numerical argument,
1674see L<perlfunc/sqrt>.
37120919 1675
41cd218c 1676=item C<srand>
37120919 1677
4755096e 1678Give a seed the pseudorandom number generator, see L<perlfunc/srand>.
37120919 1679
41cd218c 1680=item C<sscanf>
37120919 1681
4d0de388 1682Not implemented. C<sscanf()> is C-specific, use regular expressions instead,
4755096e 1683see L<perlre>.
37120919 1684
41cd218c 1685=item C<stat>
37120919 1686
4755096e 1687This is identical to Perl's builtin C<stat()> function
d7f8936a 1688for returning information about files and directories.
37120919 1689
41cd218c 1690=item C<strcat>
37120919 1691
4d0de388 1692Not implemented. C<strcat()> is C-specific, use C<.=> instead, see L<perlop>.
37120919 1693
41cd218c 1694=item C<strchr>
37120919 1695
4d0de388 1696Not implemented. C<strchr()> is C-specific, see L<perlfunc/index> instead.
37120919 1697
41cd218c 1698=item C<strcmp>
37120919 1699
4d0de388 1700Not implemented. C<strcmp()> is C-specific, use C<eq> or C<cmp> instead, see L<perlop>.
37120919 1701
41cd218c 1702=item C<strcoll>
37120919 1703
4755096e
GS
1704This is identical to the C function C<strcoll()>
1705for collating (comparing) strings transformed using
1706the C<strxfrm()> function. Not really needed since
1707Perl can do this transparently, see L<perllocale>.
37120919 1708
393aa92a
KW
1709Beware that in a UTF-8 locale, anything you pass to this function must
1710be in UTF-8; and when not in a UTF-8 locale, anything passed must not be
1711UTF-8 encoded.
1712
41cd218c 1713=item C<strcpy>
37120919 1714
4d0de388 1715Not implemented. C<strcpy()> is C-specific, use C<=> instead, see L<perlop>.
37120919 1716
41cd218c 1717=item C<strcspn>
37120919 1718
4d0de388 1719Not implemented. C<strcspn()> is C-specific, use regular expressions instead,
4755096e 1720see L<perlre>.
37120919 1721
41cd218c 1722=item C<strerror>
37120919
AD
1723
1724Returns the error string for the specified errno.
4d0de388 1725Identical to the string form of C<$!>, see L<perlvar/$ERRNO>.
37120919 1726
41cd218c 1727=item C<strftime>
37120919 1728
cb1a09d0
AD
1729Convert date and time information to string. Returns the string.
1730
1731Synopsis:
1732
b70c169c
FC
1733 strftime(fmt, sec, min, hour, mday, mon, year,
1734 wday = -1, yday = -1, isdst = -1)
cb1a09d0 1735
4d0de388
KW
1736The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero,
1737I<i.e.>, January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The
1738year (C<year>) is given in years since 1900, I<i.e.>, the year 1995 is 95; the
cb1a09d0 1739year 2001 is 101. Consult your system's C<strftime()> manpage for details
659b4938 1740about these and the other arguments.
f14c76ed 1741
659b4938
DD
1742If you want your code to be portable, your format (C<fmt>) argument
1743should use only the conversion specifiers defined by the ANSI C
f14c76ed
RGS
1744standard (C89, to play safe). These are C<aAbBcdHIjmMpSUwWxXyYZ%>.
1745But even then, the B<results> of some of the conversion specifiers are
1746non-portable. For example, the specifiers C<aAbBcpZ> change according
1747to the locale settings of the user, and both how to set locales (the
1748locale names) and what output to expect are non-standard.
1749The specifier C<c> changes according to the timezone settings of the
1750user and the timezone computation rules of the operating system.
1751The C<Z> specifier is notoriously unportable since the names of
1752timezones are non-standard. Sticking to the numeric specifiers is the
1753safest route.
1754
1755The given arguments are made consistent as though by calling
1756C<mktime()> before calling your system's C<strftime()> function,
1757except that the C<isdst> value is not affected.
cb1a09d0
AD
1758
1759The string for Tuesday, December 12, 1995.
1760
b70c169c
FC
1761 $str = POSIX::strftime( "%A, %B %d, %Y",
1762 0, 0, 0, 12, 11, 95, 2 );
cb1a09d0 1763 print "$str\n";
37120919 1764
41cd218c 1765=item C<strlen>
37120919 1766
4d0de388 1767Not implemented. C<strlen()> is C-specific, use C<length()> instead, see L<perlfunc/length>.
37120919 1768
41cd218c 1769=item C<strncat>
37120919 1770
4d0de388 1771Not implemented. C<strncat()> is C-specific, use C<.=> instead, see L<perlop>.
37120919 1772
41cd218c 1773=item C<strncmp>
37120919 1774
4d0de388 1775Not implemented. C<strncmp()> is C-specific, use C<eq> instead, see L<perlop>.
37120919 1776
41cd218c 1777=item C<strncpy>
37120919 1778
4d0de388 1779Not implemented. C<strncpy()> is C-specific, use C<=> instead, see L<perlop>.
37120919 1780
41cd218c 1781=item C<strpbrk>
37120919 1782
4d0de388 1783Not implemented. C<strpbrk()> is C-specific, use regular expressions instead,
4755096e 1784see L<perlre>.
37120919 1785
41cd218c 1786=item C<strrchr>
37120919 1787
4d0de388 1788Not implemented. C<strrchr()> is C-specific, see L<perlfunc/rindex> instead.
37120919 1789
41cd218c 1790=item C<strspn>
37120919 1791
4d0de388 1792Not implemented. C<strspn()> is C-specific, use regular expressions instead,
4755096e 1793see L<perlre>.
37120919 1794
41cd218c 1795=item C<strstr>
37120919 1796
4755096e
GS
1797This is identical to Perl's builtin C<index()> function,
1798see L<perlfunc/index>.
37120919 1799
41cd218c 1800=item C<strtod>
37120919 1801
a89d8a78
DH
1802String to double translation. Returns the parsed number and the number
1803of characters in the unparsed portion of the string. Truly
41cd218c 1804POSIX-compliant systems set C<$!> (C<$ERRNO>) to indicate a translation
4d0de388 1805error, so clear C<$!> before calling C<strtod>. However, non-POSIX systems
41cd218c 1806may not check for overflow, and therefore will never set C<$!>.
a89d8a78 1807
4d0de388 1808C<strtod> respects any POSIX C<setlocale()> C<LC_TIME> settings,
458680b3 1809regardless of whether or not it is called from Perl code that is within
aa2bc4d3
KW
1810the scope of S<C<use locale>>. This means it should not be used in a
1811threaded application unless it's certain that the underlying locale is C
1812or POSIX. This is because it otherwise changes the locale, which
1813globally affects all threads simultaneously.
a89d8a78 1814
41cd218c 1815To parse a string C<$str> as a floating point number use
a89d8a78
DH
1816
1817 $! = 0;
1818 ($num, $n_unparsed) = POSIX::strtod($str);
1819
41cd218c 1820The second returned item and C<$!> can be used to check for valid input:
a89d8a78 1821
6309100e
DM
1822 if (($str eq '') || ($n_unparsed != 0) || $!) {
1823 die "Non-numeric input $str" . ($! ? ": $!\n" : "\n");
a89d8a78
DH
1824 }
1825
4d0de388 1826When called in a scalar context C<strtod> returns the parsed number.
37120919 1827
41cd218c 1828=item C<strtok>
37120919 1829
4d0de388 1830Not implemented. C<strtok()> is C-specific, use regular expressions instead, see
4755096e 1831L<perlre>, or L<perlfunc/split>.
37120919 1832
41cd218c 1833=item C<strtol>
37120919 1834
a89d8a78
DH
1835String to (long) integer translation. Returns the parsed number and
1836the number of characters in the unparsed portion of the string. Truly
41cd218c
KW
1837POSIX-compliant systems set C<$!> (C<$ERRNO>) to indicate a translation
1838error, so clear C<$!> before calling C<strtol>. However, non-POSIX systems
1839may not check for overflow, and therefore will never set C<$!>.
a89d8a78 1840
41cd218c 1841C<strtol> should respect any POSIX I<setlocale()> settings.
a89d8a78 1842
41cd218c 1843To parse a string C<$str> as a number in some base C<$base> use
a89d8a78
DH
1844
1845 $! = 0;
1846 ($num, $n_unparsed) = POSIX::strtol($str, $base);
1847
1848The base should be zero or between 2 and 36, inclusive. When the base
4d0de388 1849is zero or omitted C<strtol> will use the string itself to determine the
a89d8a78
DH
1850base: a leading "0x" or "0X" means hexadecimal; a leading "0" means
1851octal; any other leading characters mean decimal. Thus, "1234" is
1852parsed as a decimal number, "01234" as an octal number, and "0x1234"
1853as a hexadecimal number.
1854
41cd218c 1855The second returned item and C<$!> can be used to check for valid input:
a89d8a78
DH
1856
1857 if (($str eq '') || ($n_unparsed != 0) || !$!) {
1858 die "Non-numeric input $str" . $! ? ": $!\n" : "\n";
1859 }
1860
4d0de388 1861When called in a scalar context C<strtol> returns the parsed number.
a89d8a78 1862
0ff7b9da
JH
1863=item C<strtold>
1864
1865Like L</strtod> but for long doubles. Defined only if the
1866system supports long doubles.
1867
41cd218c 1868=item C<strtoul>
a89d8a78 1869
41cd218c
KW
1870String to unsigned (long) integer translation. C<strtoul()> is identical
1871to C<strtol()> except that C<strtoul()> only parses unsigned integers. See
4755096e 1872L</strtol> for details.
a89d8a78 1873
41cd218c
KW
1874Note: Some vendors supply C<strtod()> and C<strtol()> but not C<strtoul()>.
1875Other vendors that do supply C<strtoul()> parse "-1" as a valid value.
37120919 1876
41cd218c 1877=item C<strxfrm>
37120919 1878
cb1a09d0
AD
1879String transformation. Returns the transformed string.
1880
1881 $dst = POSIX::strxfrm( $src );
37120919 1882
4755096e
GS
1883Used in conjunction with the C<strcoll()> function, see L</strcoll>.
1884
1885Not really needed since Perl can do this transparently, see
1886L<perllocale>.
1887
393aa92a
KW
1888Beware that in a UTF-8 locale, anything you pass to this function must
1889be in UTF-8; and when not in a UTF-8 locale, anything passed must not be
1890UTF-8 encoded.
1891
41cd218c 1892=item C<sysconf>
37120919
AD
1893
1894Retrieves values of system configurable variables.
1895
1896The following will get the machine's clock speed.
1897
1898 $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK );
1899
1900Returns C<undef> on failure.
1901
41cd218c 1902=item C<system>
37120919 1903
4755096e
GS
1904This is identical to Perl's builtin C<system()> function, see
1905L<perlfunc/system>.
37120919 1906
41cd218c 1907=item C<tan>
37120919 1908
4755096e 1909This is identical to the C function C<tan()>, returning the
c2e66d9e 1910tangent of the numerical argument. See also L<Math::Trig>.
37120919 1911
41cd218c 1912=item C<tanh>
37120919 1913
4755096e 1914This is identical to the C function C<tanh()>, returning the
c2e66d9e 1915hyperbolic tangent of the numerical argument. See also L<Math::Trig>.
37120919 1916
41cd218c 1917=item C<tcdrain>
37120919 1918
4755096e
GS
1919This is similar to the C function C<tcdrain()> for draining
1920the output queue of its argument stream.
37120919
AD
1921
1922Returns C<undef> on failure.
1923
41cd218c 1924=item C<tcflow>
37120919 1925
4755096e
GS
1926This is similar to the C function C<tcflow()> for controlling
1927the flow of its argument stream.
37120919
AD
1928
1929Returns C<undef> on failure.
1930
41cd218c 1931=item C<tcflush>
37120919 1932
4755096e 1933This is similar to the C function C<tcflush()> for flushing
cc767757 1934the I/O buffers of its argument stream.
37120919
AD
1935
1936Returns C<undef> on failure.
1937
41cd218c 1938=item C<tcgetpgrp>
37120919 1939
4755096e
GS
1940This is identical to the C function C<tcgetpgrp()> for returning the
1941process group identifier of the foreground process group of the controlling
1942terminal.
37120919 1943
41cd218c 1944=item C<tcsendbreak>
37120919 1945
4755096e
GS
1946This is similar to the C function C<tcsendbreak()> for sending
1947a break on its argument stream.
37120919
AD
1948
1949Returns C<undef> on failure.
1950
41cd218c 1951=item C<tcsetpgrp>
37120919 1952
4755096e
GS
1953This is similar to the C function C<tcsetpgrp()> for setting the
1954process group identifier of the foreground process group of the controlling
1955terminal.
37120919
AD
1956
1957Returns C<undef> on failure.
1958
9d233e12
JH
1959=item C<tgamma>
1960
1961The Gamma function [C99].
1962
1963See also L</lgamma>.
1964
41cd218c 1965=item C<time>
37120919 1966
4755096e
GS
1967This is identical to Perl's builtin C<time()> function
1968for returning the number of seconds since the epoch
1969(whatever it is for the system), see L<perlfunc/time>.
37120919 1970
41cd218c 1971=item C<times>
37120919 1972
41cd218c 1973The C<times()> function returns elapsed realtime since some point in the past
37120919
AD
1974(such as system startup), user and system times for this process, and user
1975and system times used by child processes. All times are returned in clock
1976ticks.
1977
4d0de388 1978 ($realtime, $user, $system, $cuser, $csystem)
b70c169c 1979 = POSIX::times();
37120919
AD
1980
1981Note: Perl's builtin C<times()> function returns four values, measured in
1982seconds.
1983
41cd218c 1984=item C<tmpfile>
37120919 1985
4d0de388 1986Not implemented. Use method C<IO::File::new_tmpfile()> instead, or see L<File::Temp>.
37120919 1987
41cd218c 1988=item C<tmpnam>
37120919 1989
60cba15a 1990For security reasons, which are probably detailed in your system's
41cd218c 1991documentation for the C library C<tmpnam()> function, this interface
26acb4d0 1992is no longer available; instead use L<File::Temp>.
4755096e 1993
41cd218c 1994=item C<tolower>
37120919 1995
4755096e 1996This is identical to the C function, except that it can apply to a single
4d0de388
KW
1997character or to a whole string, and currently operates as if the locale
1998always is "C". Consider using the C<lc()> function, see L<perlfunc/lc>,
4755096e
GS
1999see L<perlfunc/lc>, or the equivalent C<\L> operator inside doublequotish
2000strings.
37120919 2001
41cd218c 2002=item C<toupper>
37120919 2003
4d0de388
KW
2004This is similar to the C function, except that it can apply to a single
2005character or to a whole string, and currently operates as if the locale
2006always is "C". Consider using the C<uc()> function, see L<perlfunc/uc>,
2007or the equivalent C<\U> operator inside doublequotish strings.
37120919 2008
9d233e12
JH
2009=item C<trunc>
2010
2011Returns the integer toward zero from the argument [C99].
2012
2013See also L</ceil>, L</floor>, and L</round>.
2014
41cd218c 2015=item C<ttyname>
37120919 2016
4755096e
GS
2017This is identical to the C function C<ttyname()> for returning the
2018name of the current terminal.
37120919 2019
41cd218c 2020=item C<tzname>
37120919 2021
cb1a09d0
AD
2022Retrieves the time conversion information from the C<tzname> variable.
2023
2024 POSIX::tzset();
2025 ($std, $dst) = POSIX::tzname();
37120919 2026
41cd218c 2027=item C<tzset>
37120919 2028
4755096e
GS
2029This is identical to the C function C<tzset()> for setting
2030the current timezone based on the environment variable C<TZ>,
2031to be used by C<ctime()>, C<localtime()>, C<mktime()>, and C<strftime()>
2032functions.
37120919 2033
41cd218c 2034=item C<umask>
37120919 2035
4755096e
GS
2036This is identical to Perl's builtin C<umask()> function
2037for setting (and querying) the file creation permission mask,
2038see L<perlfunc/umask>.
37120919 2039
41cd218c 2040=item C<uname>
37120919 2041
cb1a09d0
AD
2042Get name of current operating system.
2043
b70c169c
FC
2044 ($sysname, $nodename, $release, $version, $machine)
2045 = POSIX::uname();
4755096e
GS
2046
2047Note that the actual meanings of the various fields are not
2048that well standardized, do not expect any great portability.
2049The C<$sysname> might be the name of the operating system,
2050the C<$nodename> might be the name of the host, the C<$release>
2051might be the (major) release number of the operating system,
2052the C<$version> might be the (minor) release number of the
2053operating system, and the C<$machine> might be a hardware identifier.
2054Maybe.
37120919 2055
41cd218c 2056=item C<ungetc>
37120919 2057
4d0de388 2058Not implemented. Use method C<IO::Handle::ungetc()> instead.
37120919 2059
41cd218c 2060=item C<unlink>
37120919 2061
4755096e
GS
2062This is identical to Perl's builtin C<unlink()> function
2063for removing files, see L<perlfunc/unlink>.
37120919 2064
41cd218c 2065=item C<utime>
37120919 2066
4755096e
GS
2067This is identical to Perl's builtin C<utime()> function
2068for changing the time stamps of files and directories,
2069see L<perlfunc/utime>.
37120919 2070
41cd218c 2071=item C<vfprintf>
37120919 2072
4d0de388 2073Not implemented. C<vfprintf()> is C-specific, see L<perlfunc/printf> instead.
37120919 2074
41cd218c 2075=item C<vprintf>
37120919 2076
4d0de388 2077Not implemented. C<vprintf()> is C-specific, see L<perlfunc/printf> instead.
37120919 2078
41cd218c 2079=item C<vsprintf>
37120919 2080
4d0de388 2081Not implemented. C<vsprintf()> is C-specific, see L<perlfunc/sprintf> instead.
37120919 2082
41cd218c 2083=item C<wait>
37120919 2084
4755096e
GS
2085This is identical to Perl's builtin C<wait()> function,
2086see L<perlfunc/wait>.
37120919 2087
41cd218c 2088=item C<waitpid>
37120919 2089
cb1a09d0 2090Wait for a child process to change state. This is identical to Perl's
4755096e 2091builtin C<waitpid()> function, see L<perlfunc/waitpid>.
cb1a09d0 2092
2ac1ef3d 2093 $pid = POSIX::waitpid( -1, POSIX::WNOHANG );
cb1a09d0 2094 print "status = ", ($? / 256), "\n";
37120919 2095
41cd218c 2096=item C<wcstombs>
37120919 2097
cb1a09d0 2098This is identical to the C function C<wcstombs()>.
351ab2ad
JH
2099
2100See L</mblen>.
37120919 2101
41cd218c 2102=item C<wctomb>
37120919 2103
cb1a09d0 2104This is identical to the C function C<wctomb()>.
351ab2ad
JH
2105
2106See L</mblen>.
37120919 2107
41cd218c 2108=item C<write>
37120919 2109
cb1a09d0
AD
2110Write to a file. This uses file descriptors such as those obtained by
2111calling C<POSIX::open>.
2112
2113 $fd = POSIX::open( "foo", &POSIX::O_WRONLY );
2114 $buf = "hello";
a0604b4c 2115 $bytes = POSIX::write( $fd, $buf, 5 );
37120919
AD
2116
2117Returns C<undef> on failure.
2118
4755096e
GS
2119See also L<perlfunc/syswrite>.
2120
37120919
AD
2121=back
2122
2123=head1 CLASSES
2124
41cd218c 2125=head2 C<POSIX::SigAction>
37120919
AD
2126
2127=over 8
2128
41cd218c 2129=item C<new>
37120919 2130
cb1a09d0 2131Creates a new C<POSIX::SigAction> object which corresponds to the C
3609ea0d
JH
2132C<struct sigaction>. This object will be destroyed automatically when
2133it is no longer needed. The first parameter is the handler, a sub
2134reference. The second parameter is a C<POSIX::SigSet> object, it
2135defaults to the empty set. The third parameter contains the
28757baa 2136C<sa_flags>, it defaults to 0.
cb1a09d0 2137
28757baa 2138 $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT);
b70c169c
FC
2139 $sigaction = POSIX::SigAction->new(
2140 \&handler, $sigset, &POSIX::SA_NOCLDSTOP
2141 );
cb1a09d0 2142
d36b6582 2143This C<POSIX::SigAction> object is intended for use with the C<POSIX::sigaction()>
cb1a09d0 2144function.
37120919
AD
2145
2146=back
2147
557c0de7
BD
2148=over 8
2149
41cd218c 2150=item C<handler>
557c0de7 2151
41cd218c 2152=item C<mask>
557c0de7 2153
41cd218c 2154=item C<flags>
557c0de7
BD
2155
2156accessor functions to get/set the values of a SigAction object.
2157
2158 $sigset = $sigaction->mask;
2159 $sigaction->flags(&POSIX::SA_RESTART);
2160
41cd218c 2161=item C<safe>
d36b6582
CS
2162
2163accessor function for the "safe signals" flag of a SigAction object; see
2164L<perlipc> for general information on safe (a.k.a. "deferred") signals. If
2165you wish to handle a signal safely, use this accessor to set the "safe" flag
2166in the C<POSIX::SigAction> object:
2167
2168 $sigaction->safe(1);
2169
2170You may also examine the "safe" flag on the output action object which is
2171filled in when given as the third parameter to C<POSIX::sigaction()>:
2172
2173 sigaction(SIGINT, $new_action, $old_action);
2174 if ($old_action->safe) {
2175 # previous SIGINT handler used safe signals
2176 }
2177
557c0de7
BD
2178=back
2179
41cd218c 2180=head2 C<POSIX::SigRt>
3609ea0d
JH
2181
2182=over 8
2183
41cd218c 2184=item C<%SIGRT>
3609ea0d
JH
2185
2186A hash of the POSIX realtime signal handlers. It is an extension of
41cd218c
KW
2187the standard C<%SIG>, the C<$POSIX::SIGRT{SIGRTMIN}> is roughly equivalent
2188to C<$SIG{SIGRTMIN}>, but the right POSIX moves (see below) are made with
2189the C<POSIX::SigSet> and C<POSIX::sigaction> instead of accessing the C<%SIG>.
3609ea0d 2190
41cd218c 2191You can set the C<%POSIX::SIGRT> elements to set the POSIX realtime
3609ea0d
JH
2192signal handlers, use C<delete> and C<exists> on the elements, and use
2193C<scalar> on the C<%POSIX::SIGRT> to find out how many POSIX realtime
41cd218c 2194signals there are available S<C<(SIGRTMAX - SIGRTMIN + 1>>, the C<SIGRTMAX> is
3609ea0d
JH
2195a valid POSIX realtime signal).
2196
41cd218c 2197Setting the C<%SIGRT> elements is equivalent to calling this:
3609ea0d
JH
2198
2199 sub new {
2200 my ($rtsig, $handler, $flags) = @_;
b8921b3e 2201 my $sigset = POSIX::SigSet($rtsig);
b70c169c 2202 my $sigact = POSIX::SigAction->new($handler,$sigset,$flags);
3609ea0d
JH
2203 sigaction($rtsig, $sigact);
2204 }
2205
2206The flags default to zero, if you want something different you can
41cd218c 2207either use C<local> on C<$POSIX::SigRt::SIGACTION_FLAGS>, or you can
3609ea0d 2208derive from POSIX::SigRt and define your own C<new()> (the tied hash
41cd218c
KW
2209STORE method of the C<%SIGRT> calls C<new($rtsig, $handler, $SIGACTION_FLAGS)>,
2210where the C<$rtsig> ranges from zero to S<C<SIGRTMAX - SIGRTMIN + 1)>>.
3609ea0d 2211
41cd218c 2212Just as with any signal, you can use C<sigaction($rtsig, undef, $oa)> to
3609ea0d
JH
2213retrieve the installed signal handler (or, rather, the signal action).
2214
2215B<NOTE:> whether POSIX realtime signals really work in your system, or
2216whether Perl has been compiled so that it works with them, is outside
2217of this discussion.
2218
41cd218c 2219=item C<SIGRTMIN>
3609ea0d
JH
2220
2221Return the minimum POSIX realtime signal number available, or C<undef>
2222if no POSIX realtime signals are available.
2223
41cd218c 2224=item C<SIGRTMAX>
3609ea0d
JH
2225
2226Return the maximum POSIX realtime signal number available, or C<undef>
2227if no POSIX realtime signals are available.
2228
2229=back
2230
41cd218c 2231=head2 C<POSIX::SigSet>
37120919
AD
2232
2233=over 8
2234
41cd218c 2235=item C<new>
37120919
AD
2236
2237Create a new SigSet object. This object will be destroyed automatically
2238when it is no longer needed. Arguments may be supplied to initialize the
2239set.
2240
2241Create an empty set.
2242
2243 $sigset = POSIX::SigSet->new;
2244
41cd218c 2245Create a set with C<SIGUSR1>.
37120919
AD
2246
2247 $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 );
2248
41cd218c 2249=item C<addset>
37120919
AD
2250
2251Add a signal to a SigSet object.
2252
2253 $sigset->addset( &POSIX::SIGUSR2 );
2254
2255Returns C<undef> on failure.
2256
41cd218c 2257=item C<delset>
37120919
AD
2258
2259Remove a signal from the SigSet object.
2260
2261 $sigset->delset( &POSIX::SIGUSR2 );
2262
2263Returns C<undef> on failure.
2264
41cd218c 2265=item C<emptyset>
37120919
AD
2266
2267Initialize the SigSet object to be empty.
2268
2269 $sigset->emptyset();
2270
2271Returns C<undef> on failure.
2272
41cd218c 2273=item C<fillset>
37120919
AD
2274
2275Initialize the SigSet object to include all signals.
2276
2277 $sigset->fillset();
2278
2279Returns C<undef> on failure.
2280
41cd218c 2281=item C<ismember>
37120919
AD
2282
2283Tests the SigSet object to see if it contains a specific signal.
2284
2285 if( $sigset->ismember( &POSIX::SIGUSR1 ) ){
2286 print "contains SIGUSR1\n";
2287 }
2288
2289=back
2290
41cd218c 2291=head2 C<POSIX::Termios>
37120919
AD
2292
2293=over 8
2294
41cd218c 2295=item C<new>
37120919
AD
2296
2297Create a new Termios object. This object will be destroyed automatically
4d0de388 2298when it is no longer needed. A Termios object corresponds to the C<termios>
41cd218c
KW
2299C struct. C<new()> mallocs a new one, C<getattr()> fills it from a file descriptor,
2300and C<setattr()> sets a file descriptor's parameters to match Termios' contents.
37120919
AD
2301
2302 $termios = POSIX::Termios->new;
2303
41cd218c 2304=item C<getattr>
37120919 2305
cb1a09d0
AD
2306Get terminal control attributes.
2307
4d0de388 2308Obtain the attributes for C<stdin>.
cb1a09d0 2309
220f811a 2310 $termios->getattr( 0 ) # Recommended for clarity.
cb1a09d0
AD
2311 $termios->getattr()
2312
2313Obtain the attributes for stdout.
2314
2315 $termios->getattr( 1 )
37120919
AD
2316
2317Returns C<undef> on failure.
2318
41cd218c 2319=item C<getcc>
37120919 2320
4d0de388 2321Retrieve a value from the C<c_cc> field of a C<termios> object. The C<c_cc> field is
37120919
AD
2322an array so an index must be specified.
2323
2324 $c_cc[1] = $termios->getcc(1);
2325
41cd218c 2326=item C<getcflag>
37120919 2327
4d0de388 2328Retrieve the C<c_cflag> field of a C<termios> object.
37120919
AD
2329
2330 $c_cflag = $termios->getcflag;
2331
41cd218c 2332=item C<getiflag>
37120919 2333
4d0de388 2334Retrieve the C<c_iflag> field of a C<termios> object.
37120919
AD
2335
2336 $c_iflag = $termios->getiflag;
2337
41cd218c 2338=item C<getispeed>
37120919
AD
2339
2340Retrieve the input baud rate.
2341
2342 $ispeed = $termios->getispeed;
2343
41cd218c 2344=item C<getlflag>
37120919 2345
4d0de388 2346Retrieve the C<c_lflag> field of a C<termios> object.
37120919
AD
2347
2348 $c_lflag = $termios->getlflag;
2349
41cd218c 2350=item C<getoflag>
37120919 2351
4d0de388 2352Retrieve the C<c_oflag> field of a C<termios> object.
37120919
AD
2353
2354 $c_oflag = $termios->getoflag;
2355
41cd218c 2356=item C<getospeed>
37120919
AD
2357
2358Retrieve the output baud rate.
2359
2360 $ospeed = $termios->getospeed;
2361
41cd218c 2362=item C<setattr>
37120919 2363
cb1a09d0
AD
2364Set terminal control attributes.
2365
2366Set attributes immediately for stdout.
2367
2368 $termios->setattr( 1, &POSIX::TCSANOW );
37120919
AD
2369
2370Returns C<undef> on failure.
2371
41cd218c 2372=item C<setcc>
37120919 2373
4d0de388 2374Set a value in the C<c_cc> field of a C<termios> object. The C<c_cc> field is an
37120919
AD
2375array so an index must be specified.
2376
6b7a6f50 2377 $termios->setcc( &POSIX::VEOF, 1 );
37120919 2378
41cd218c 2379=item C<setcflag>
37120919 2380
4d0de388 2381Set the C<c_cflag> field of a C<termios> object.
37120919 2382
55d729e4 2383 $termios->setcflag( $c_cflag | &POSIX::CLOCAL );
37120919 2384
41cd218c 2385=item C<setiflag>
37120919 2386
4d0de388 2387Set the C<c_iflag> field of a C<termios> object.
37120919 2388
55d729e4 2389 $termios->setiflag( $c_iflag | &POSIX::BRKINT );
37120919 2390
41cd218c 2391=item C<setispeed>
37120919
AD
2392
2393Set the input baud rate.
2394
2395 $termios->setispeed( &POSIX::B9600 );
2396
2397Returns C<undef> on failure.
2398
41cd218c 2399=item C<setlflag>
37120919 2400
4d0de388 2401Set the C<c_lflag> field of a C<termios> object.
37120919 2402
55d729e4 2403 $termios->setlflag( $c_lflag | &POSIX::ECHO );
37120919 2404
41cd218c 2405=item C<setoflag>
37120919 2406
4d0de388 2407Set the C<c_oflag> field of a C<termios> object.
37120919 2408
55d729e4 2409 $termios->setoflag( $c_oflag | &POSIX::OPOST );
37120919 2410
41cd218c 2411=item C<setospeed>
37120919
AD
2412
2413Set the output baud rate.
2414
2415 $termios->setospeed( &POSIX::B9600 );
2416
2417Returns C<undef> on failure.
2418
2419=item Baud rate values
2420
41cd218c 2421C<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
2422
2423=item Terminal interface values
2424
41cd218c 2425C<TCSADRAIN> C<TCSANOW> C<TCOON> C<TCIOFLUSH> C<TCOFLUSH> C<TCION> C<TCIFLUSH> C<TCSAFLUSH> C<TCIOFF> C<TCOOFF>
37120919 2426
41cd218c 2427=item C<c_cc> field values
37120919 2428
41cd218c 2429C<VEOF> C<VEOL> C<VERASE> C<VINTR> C<VKILL> C<VQUIT> C<VSUSP> C<VSTART> C<VSTOP> C<VMIN> C<VTIME> C<NCCS>
37120919 2430
41cd218c 2431=item C<c_cflag> field values
37120919 2432
41cd218c 2433C<CLOCAL> C<CREAD> C<CSIZE> C<CS5> C<CS6> C<CS7> C<CS8> C<CSTOPB> C<HUPCL> C<PARENB> C<PARODD>
37120919 2434
41cd218c 2435=item C<c_iflag> field values
37120919 2436
41cd218c 2437C<BRKINT> C<ICRNL> C<IGNBRK> C<IGNCR> C<IGNPAR> C<INLCR> C<INPCK> C<ISTRIP> C<IXOFF> C<IXON> C<PARMRK>
37120919 2438
41cd218c 2439=item C<c_lflag> field values
37120919 2440
41cd218c 2441C<ECHO> C<ECHOE> C<ECHOK> C<ECHONL> C<ICANON> C<IEXTEN> C<ISIG> C<NOFLSH> C<TOSTOP>
37120919 2442
41cd218c 2443=item C<c_oflag> field values
37120919 2444
41cd218c 2445C<OPOST>
37120919
AD
2446
2447=back
2448
2449=head1 PATHNAME CONSTANTS
2450
2451=over 8
2452
2453=item Constants
2454
41cd218c
KW
2455C<_PC_CHOWN_RESTRICTED> C<_PC_LINK_MAX> C<_PC_MAX_CANON> C<_PC_MAX_INPUT> C<_PC_NAME_MAX>
2456C<_PC_NO_TRUNC> C<_PC_PATH_MAX> C<_PC_PIPE_BUF> C<_PC_VDISABLE>
37120919
AD
2457
2458=back
2459
2460=head1 POSIX CONSTANTS
2461
2462=over 8
2463
2464=item Constants
2465
41cd218c
KW
2466C<_POSIX_ARG_MAX> C<_POSIX_CHILD_MAX> C<_POSIX_CHOWN_RESTRICTED> C<_POSIX_JOB_CONTROL>
2467C<_POSIX_LINK_MAX> C<_POSIX_MAX_CANON> C<_POSIX_MAX_INPUT> C<_POSIX_NAME_MAX>
2468C<_POSIX_NGROUPS_MAX> C<_POSIX_NO_TRUNC> C<_POSIX_OPEN_MAX> C<_POSIX_PATH_MAX>
2469C<_POSIX_PIPE_BUF> C<_POSIX_SAVED_IDS> C<_POSIX_SSIZE_MAX> C<_POSIX_STREAM_MAX>
2470C<_POSIX_TZNAME_MAX> C<_POSIX_VDISABLE> C<_POSIX_VERSION>
37120919
AD
2471
2472=back
2473
4fd667a8
TC
2474=head1 RESOURCE CONSTANTS
2475
2476Imported with the C<:sys_resource_h> tag.
2477
2478=over 8
2479
2480=item Constants
2481
2482C<PRIO_PROCESS> C<PRIO_PGRP> C<PRIO_USER>
2483
2484=back
2485
37120919
AD
2486=head1 SYSTEM CONFIGURATION
2487
2488=over 8
2489
2490=item Constants
2491
41cd218c
KW
2492C<_SC_ARG_MAX> C<_SC_CHILD_MAX> C<_SC_CLK_TCK> C<_SC_JOB_CONTROL> C<_SC_NGROUPS_MAX>
2493C<_SC_OPEN_MAX> C<_SC_PAGESIZE> C<_SC_SAVED_IDS> C<_SC_STREAM_MAX> C<_SC_TZNAME_MAX>
2494C<_SC_VERSION>
37120919
AD
2495
2496=back
2497
2498=head1 ERRNO
2499
2500=over 8
2501
2502=item Constants
2503
41cd218c
KW
2504C<E2BIG> C<EACCES> C<EADDRINUSE> C<EADDRNOTAVAIL> C<EAFNOSUPPORT> C<EAGAIN> C<EALREADY> C<EBADF> C<EBADMSG>
2505C<EBUSY> C<ECANCELED> C<ECHILD> C<ECONNABORTED> C<ECONNREFUSED> C<ECONNRESET> C<EDEADLK> C<EDESTADDRREQ>
2506C<EDOM> C<EDQUOT> C<EEXIST> C<EFAULT> C<EFBIG> C<EHOSTDOWN> C<EHOSTUNREACH> C<EIDRM> C<EILSEQ> C<EINPROGRESS>
2507C<EINTR> C<EINVAL> C<EIO> C<EISCONN> C<EISDIR> C<ELOOP> C<EMFILE> C<EMLINK> C<EMSGSIZE> C<ENAMETOOLONG>
2508C<ENETDOWN> C<ENETRESET> C<ENETUNREACH> C<ENFILE> C<ENOBUFS> C<ENODATA> C<ENODEV> C<ENOENT> C<ENOEXEC>
2509C<ENOLCK> C<ENOLINK> C<ENOMEM> C<ENOMSG> C<ENOPROTOOPT> C<ENOSPC> C<ENOSR> C<ENOSTR> C<ENOSYS> C<ENOTBLK>
2510C<ENOTCONN> C<ENOTDIR> C<ENOTEMPTY> C<ENOTRECOVERABLE> C<ENOTSOCK> C<ENOTSUP> C<ENOTTY> C<ENXIO>
2511C<EOPNOTSUPP> C<EOTHER> C<EOVERFLOW> C<EOWNERDEAD> C<EPERM> C<EPFNOSUPPORT> C<EPIPE> C<EPROCLIM> C<EPROTO>
2512C<EPROTONOSUPPORT> C<EPROTOTYPE> C<ERANGE> C<EREMOTE> C<ERESTART> C<EROFS> C<ESHUTDOWN>
2513C<ESOCKTNOSUPPORT> C<ESPIPE> C<ESRCH> C<ESTALE> C<ETIME> C<ETIMEDOUT> C<ETOOMANYREFS> C<ETXTBSY> C<EUSERS>
2514C<EWOULDBLOCK> C<EXDEV>
37120919
AD
2515
2516=back
2517
2518=head1 FCNTL
2519
2520=over 8
2521
2522=item Constants
2523
41cd218c
KW
2524C<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>
2525C<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>
2526C<O_RDONLY> C<O_RDWR> C<O_TRUNC> C<O_WRONLY>
37120919
AD
2527
2528=back
2529
2530=head1 FLOAT
2531
2532=over 8
2533
2534=item Constants
2535
41cd218c
KW
2536C<DBL_DIG> C<DBL_EPSILON> C<DBL_MANT_DIG> C<DBL_MAX> C<DBL_MAX_10_EXP> C<DBL_MAX_EXP> C<DBL_MIN>
2537C<DBL_MIN_10_EXP> C<DBL_MIN_EXP> C<FLT_DIG> C<FLT_EPSILON> C<FLT_MANT_DIG> C<FLT_MAX>
2538C<FLT_MAX_10_EXP> C<FLT_MAX_EXP> C<FLT_MIN> C<FLT_MIN_10_EXP> C<FLT_MIN_EXP> C<FLT_RADIX>
2539C<FLT_ROUNDS> C<LDBL_DIG> C<LDBL_EPSILON> C<LDBL_MANT_DIG> C<LDBL_MAX> C<LDBL_MAX_10_EXP>
2540C<LDBL_MAX_EXP> C<LDBL_MIN> C<LDBL_MIN_10_EXP> C<LDBL_MIN_EXP>
37120919
AD
2541
2542=back
2543
98ab3abf
AP
2544=head1 FLOATING-POINT ENVIRONMENT
2545
2546=over 8
2547
2548=item Constants
2549
2550C<FE_DOWNWARD> C<FE_TONEAREST> C<FE_TOWARDZERO> C<FE_UPWARD>
2551on systems that support them.
2552
2553=back
2554
37120919
AD
2555=head1 LIMITS
2556
2557=over 8
2558
2559=item Constants
2560
41cd218c
KW
2561C<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>
2562C<LONG_MIN> C<MAX_CANON> C<MAX_INPUT> C<MB_LEN_MAX> C<NAME_MAX> C<NGROUPS_MAX> C<OPEN_MAX> C<PATH_MAX>
2563C<PIPE_BUF> C<SCHAR_MAX> C<SCHAR_MIN> C<SHRT_MAX> C<SHRT_MIN> C<SSIZE_MAX> C<STREAM_MAX> C<TZNAME_MAX>
2564C<UCHAR_MAX> C<UINT_MAX> C<ULONG_MAX> C<USHRT_MAX>
37120919
AD
2565
2566=back
2567
2568=head1 LOCALE
2569
2570=over 8
2571
2572=item Constants
2573
4d0de388
KW
2574C<LC_ALL> C<LC_COLLATE> C<LC_CTYPE> C<LC_MONETARY> C<LC_NUMERIC> C<LC_TIME> C<LC_MESSAGES>
2575on systems that support them.
37120919
AD
2576
2577=back
2578
2579=head1 MATH
2580
2581=over 8
2582
2583=item Constants
2584
41cd218c 2585C<HUGE_VAL>
37120919 2586
98ab3abf
AP
2587C<FP_ILOGB0> C<FP_ILOGBNAN> C<FP_INFINITE> C<FP_NAN> C<FP_NORMAL> C<FP_SUBNORMAL> C<FP_ZERO>
2588C<INFINITY> C<NAN> C<Inf> C<NaN>
2589C<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>
2590C<M_PI_2> C<M_PI_4> C<M_SQRT1_2> C<M_SQRT2>
2591on systems with C99 support.
2592
37120919
AD
2593=back
2594
2595=head1 SIGNAL
2596
2597=over 8
2598
2599=item Constants
2600
41cd218c
KW
2601C<SA_NOCLDSTOP> C<SA_NOCLDWAIT> C<SA_NODEFER> C<SA_ONSTACK> C<SA_RESETHAND> C<SA_RESTART>
2602C<SA_SIGINFO> C<SIGABRT> C<SIGALRM> C<SIGCHLD> C<SIGCONT> C<SIGFPE> C<SIGHUP> C<SIGILL> C<SIGINT>
2603C<SIGKILL> C<SIGPIPE> C<SIGQUIT> C<SIGSEGV> C<SIGSTOP> C<SIGTERM> C<SIGTSTP> C<SIGTTIN> C<SIGTTOU>
2604C<SIGUSR1> C<SIGUSR2> C<SIG_BLOCK> C<SIG_DFL> C<SIG_ERR> C<SIG_IGN> C<SIG_SETMASK>
2605C<SIG_UNBLOCK>
34e79b75
DIM
2606C<ILL_ILLOPC> C<ILL_ILLOPN> C<ILL_ILLADR> C<ILL_ILLTRP> C<ILL_PRVOPC> C<ILL_PRVREG> C<ILL_COPROC>
2607C<ILL_BADSTK> C<FPE_INTDIV> C<FPE_INTOVF> C<FPE_FLTDIV> C<FPE_FLTOVF> C<FPE_FLTUND> C<FPE_FLTRES>
2608C<FPE_FLTINV> C<FPE_FLTSUB> C<SEGV_MAPERR> C<SEGV_ACCERR> C<BUS_ADRALN> C<BUS_ADRERR>
2609C<BUS_OBJERR> C<TRAP_BRKPT> C<TRAP_TRACE> C<CLD_EXITED> C<CLD_KILLED> C<CLD_DUMPED> C<CLD_TRAPPED>
2610C<CLD_STOPPED> C<CLD_CONTINUED> C<POLL_IN> C<POLL_OUT> C<POLL_MSG> C<POLL_ERR> C<POLL_PRI>
2611C<POLL_HUP> C<SI_USER> C<SI_QUEUE> C<SI_TIMER> C<SI_ASYNCIO> C<SI_MESGQ>
37120919
AD
2612
2613=back
2614
2615=head1 STAT
2616
2617=over 8
2618
2619=item Constants
2620
41cd218c
KW
2621C<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>
2622C<S_IWUSR> C<S_IXGRP> C<S_IXOTH> C<S_IXUSR>
37120919
AD
2623
2624=item Macros
2625
41cd218c 2626C<S_ISBLK> C<S_ISCHR> C<S_ISDIR> C<S_ISFIFO> C<S_ISREG>
37120919
AD
2627
2628=back
2629
2630=head1 STDLIB
2631
2632=over 8
2633
2634=item Constants
2635
41cd218c 2636C<EXIT_FAILURE> C<EXIT_SUCCESS> C<MB_CUR_MAX> C<RAND_MAX>
37120919
AD
2637
2638=back
2639
2640=head1 STDIO
2641
2642=over 8
2643
2644=item Constants
2645
1cb852db 2646C<BUFSIZ> C<EOF> C<FILENAME_MAX> C<L_ctermid> C<L_cuserid> C<TMP_MAX>
37120919
AD
2647
2648=back
2649
2650=head1 TIME
2651
2652=over 8
2653
2654=item Constants
2655
41cd218c 2656C<CLK_TCK> C<CLOCKS_PER_SEC>
37120919
AD
2657
2658=back
2659
2660=head1 UNISTD
2661
2662=over 8
2663
2664=item Constants
2665
41cd218c 2666C<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
2667
2668=back
2669
2670=head1 WAIT
2671
2672=over 8
2673
2674=item Constants
2675
41cd218c 2676C<WNOHANG> C<WUNTRACED>
37120919 2677
9d6eb86e
JH
2678=over 16
2679
41cd218c 2680=item C<WNOHANG>
9d6eb86e
JH
2681
2682Do not suspend the calling process until a child process
2683changes state but instead return immediately.
2684
41cd218c 2685=item C<WUNTRACED>
9d6eb86e
JH
2686
2687Catch stopped child processes.
2688
2689=back
2690
37120919
AD
2691=item Macros
2692
41cd218c 2693C<WIFEXITED> C<WEXITSTATUS> C<WIFSIGNALED> C<WTERMSIG> C<WIFSTOPPED> C<WSTOPSIG>
37120919 2694
9d6eb86e
JH
2695=over 16
2696
41cd218c 2697=item C<WIFEXITED>
9d6eb86e 2698
41cd218c 2699C<WIFEXITED(${^CHILD_ERROR_NATIVE})> returns true if the child process
12a72a5a 2700exited normally (C<exit()> or by falling off the end of C<main()>)
9d6eb86e 2701
41cd218c 2702=item C<WEXITSTATUS>
9d6eb86e 2703
41cd218c
KW
2704C<WEXITSTATUS(${^CHILD_ERROR_NATIVE})> returns the normal exit status of
2705the child process (only meaningful if C<WIFEXITED(${^CHILD_ERROR_NATIVE})>
12a72a5a 2706is true)
9d6eb86e 2707
41cd218c 2708=item C<WIFSIGNALED>
9d6eb86e 2709
41cd218c 2710C<WIFSIGNALED(${^CHILD_ERROR_NATIVE})> returns true if the child process
12a72a5a 2711terminated because of a signal
9d6eb86e 2712
41cd218c 2713=item C<WTERMSIG>
9d6eb86e 2714
41cd218c
KW
2715C<WTERMSIG(${^CHILD_ERROR_NATIVE})> returns the signal the child process
2716terminated for (only meaningful if
2717C<WIFSIGNALED(${^CHILD_ERROR_NATIVE})>
12a72a5a 2718is true)
9d6eb86e 2719
41cd218c 2720=item C<WIFSTOPPED>
9d6eb86e 2721
41cd218c 2722C<WIFSTOPPED(${^CHILD_ERROR_NATIVE})> returns true if the child process is
12a72a5a 2723currently stopped (can happen only if you specified the WUNTRACED flag
41cd218c 2724to C<waitpid()>)
9d6eb86e 2725
41cd218c 2726=item C<WSTOPSIG>
9d6eb86e 2727
41cd218c
KW
2728C<WSTOPSIG(${^CHILD_ERROR_NATIVE})> returns the signal the child process
2729was stopped for (only meaningful if
2730C<WIFSTOPPED(${^CHILD_ERROR_NATIVE})>
12a72a5a 2731is true)
9d6eb86e
JH
2732
2733=back
2734
37120919
AD
2735=back
2736
a28fff51
SH
2737=head1 WINSOCK
2738
2739(Windows only.)
2740
2741=over 8
2742
2743=item Constants
2744
2745C<WSAEINTR> C<WSAEBADF> C<WSAEACCES> C<WSAEFAULT> C<WSAEINVAL> C<WSAEMFILE> C<WSAEWOULDBLOCK>
2746C<WSAEINPROGRESS> C<WSAEALREADY> C<WSAENOTSOCK> C<WSAEDESTADDRREQ> C<WSAEMSGSIZE>
2747C<WSAEPROTOTYPE> C<WSAENOPROTOOPT> C<WSAEPROTONOSUPPORT> C<WSAESOCKTNOSUPPORT>
2748C<WSAEOPNOTSUPP> C<WSAEPFNOSUPPORT> C<WSAEAFNOSUPPORT> C<WSAEADDRINUSE>
2749C<WSAEADDRNOTAVAIL> C<WSAENETDOWN> C<WSAENETUNREACH> C<WSAENETRESET> C<WSAECONNABORTED>
2750C<WSAECONNRESET> C<WSAENOBUFS> C<WSAEISCONN> C<WSAENOTCONN> C<WSAESHUTDOWN>
2751C<WSAETOOMANYREFS> C<WSAETIMEDOUT> C<WSAECONNREFUSED> C<WSAELOOP> C<WSAENAMETOOLONG>
2752C<WSAEHOSTDOWN> C<WSAEHOSTUNREACH> C<WSAENOTEMPTY> C<WSAEPROCLIM> C<WSAEUSERS>
2753C<WSAEDQUOT> C<WSAESTALE> C<WSAEREMOTE> C<WSAEDISCON> C<WSAENOMORE> C<WSAECANCELLED>
2754C<WSAEINVALIDPROCTABLE> C<WSAEINVALIDPROVIDER> C<WSAEPROVIDERFAILEDINIT>
2755C<WSAEREFUSED>
2756
2757=back
2758