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