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