X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=ext%2FPOSIX%2FPOSIX.pod;h=7263d0a62a090af23befb0133824b3d772ec23a1;hb=8565c31a574ba4f7dc8cd69b66988949074e120d;hp=c13e8397cc2b620c409191e1fd4e4ae3b2aa1399;hpb=b0b407d10583e9cf91fd5f5f7c28712d2c30c70e;p=p5sagit%2Fp5-mst-13.2.git diff --git a/ext/POSIX/POSIX.pod b/ext/POSIX/POSIX.pod index c13e839..7263d0a 100644 --- a/ext/POSIX/POSIX.pod +++ b/ext/POSIX/POSIX.pod @@ -19,10 +19,14 @@ POSIX - Perl interface to IEEE Std 1003.1 The POSIX module permits you to access all (or nearly all) the standard POSIX 1003.1 identifiers. Many of these identifiers have been given Perl-ish -interfaces. Things which are C<#defines> in C, like EINTR or O_NDELAY, are -automatically exported into your namespace. All functions are only exported -if you ask for them explicitly. Most likely people will prefer to use the -fully-qualified function names. +interfaces. + +I with the exception of any POSIX +functions with the same name as a built-in Perl function, such as +C, C, C, C, etc.., which will be exported +only if you ask for them explicitly. This is an unfortunate backwards +compatibility feature. You can stop the exporting by saying C and then use the fully qualified names (ie. C). This document gives a condensed list of the features available in the POSIX module. Consult your operating system's manpages for general information on @@ -42,7 +46,7 @@ the standard distribution. It incorporates autoloading, namespace games, and dynamic loading of code that's in Perl, C, or both. It's a great source of wisdom. -=head1 CAVEATS +=head1 CAVEATS A few functions are not implemented because they are C specific. If you attempt to call these, they will print a message telling you that they @@ -68,6 +72,12 @@ all. This could be construed to be a bug. This is identical to the C function C<_exit()>. It exits the program immediately which means among other things buffered I/O is B flushed. +Note that when using threads and in Linux this is B a good way to +exit a thread because in Linux processes and threads are kind of the +same thing (Note: while this is the situation in early 2003 there are +projects under way to have threads with more POSIXly semantics in Linux). +If you want not to return from a thread, detach the thread. + =item abort This is identical to the C function C. It terminates the @@ -95,7 +105,7 @@ I. =item acos This is identical to the C function C, returning -the arcus cosine of its numerical argument. +the arcus cosine of its numerical argument. See also L. =item alarm @@ -115,13 +125,13 @@ and it is called thusly $wday, $yday, $isdst); The C<$mon> is zero-based: January equals C<0>. The C<$year> is -1900-based: 2001 equals C<101>. The C<$wday>, C<$yday>, and C<$isdst> -default to zero (and the first two are usually ignored anyway). +1900-based: 2001 equals C<101>. C<$wday> and C<$yday> default to zero +(and are usually ignored anyway), and C<$isdst> defaults to -1. =item asin This is identical to the C function C, returning -the arcus sine of its numerical argument. +the arcus sine of its numerical argument. See also L. =item assert @@ -131,13 +141,13 @@ to achieve similar things. =item atan This is identical to the C function C, returning the -arcus tangent of its numerical argument. +arcus tangent of its numerical argument. See also L. =item atan2 This is identical to Perl's builtin C function, returning the arcus tangent defined by its two numerical arguments, the I -coordinate and the I coordinate. +coordinate and the I coordinate. See also L. =item atexit @@ -191,7 +201,7 @@ to change file and directory owners and groups, see L. =item clearerr -Use the method L instead, to reset the error +Use the method C instead, to reset the error state (if any) and EOF state (if any) of the given stream. =item clock @@ -220,11 +230,12 @@ a directory handle, see L. This is identical to Perl's builtin C function, for returning the cosine of its numerical argument, see L. +See also L. =item cosh This is identical to the C function C, for returning -the hyperbolic cosine of its numeric argument. +the hyperbolic cosine of its numeric argument. See also L. =item creat @@ -244,17 +255,20 @@ Generates the path name for the controlling terminal. =item ctime -This is identical to the C function C. +This is identical to the C function C and equivalent +to C, see L and L. =item cuserid -Get the character login name of the user. +Get the login name of the owner of the current process. $name = POSIX::cuserid(); =item difftime -This is identical to the C function C. +This is identical to the C function C, for returning +the time difference (in seconds) between two times (as returned +by C), see L. =item div @@ -263,7 +277,8 @@ the modulus C<%>. =item dup -This is similar to the C function C. +This is similar to the C function C, for duplicating a file +descriptor. This uses file descriptors such as those obtained by calling C. @@ -272,7 +287,8 @@ Returns C on failure. =item dup2 -This is similar to the C function C. +This is similar to the C function C, for duplicating a file +descriptor to an another known file descriptor. This uses file descriptors such as those obtained by calling C. @@ -285,7 +301,7 @@ Returns the value of errno. $errno = POSIX::errno(); -This identical to the numerical values of the C<$!>, see L. +This identical to the numerical values of the C<$!>, see L. =item execl @@ -329,7 +345,7 @@ the absolute value of the numerical argument, see L. =item fclose -Use method C instead. +Use method C instead, or see L. =item fcntl @@ -338,11 +354,11 @@ see L. =item fdopen -Use method C instead. +Use method C instead, or see L. =item feof -Use method C instead. +Use method C instead, or see L. =item ferror @@ -351,23 +367,24 @@ Use method C instead. =item fflush Use method C instead. +See also L. =item fgetc -Use method C instead. +Use method C instead, or see L. =item fgetpos -Use method C instead. +Use method C instead, or see L. =item fgets -Use method C instead. Similar to <>, also known +Use method C instead. Similar to EE, also known as L. =item fileno -Use method C instead. +Use method C instead, or see L. =item floor @@ -378,7 +395,7 @@ integer value less than or equal to the numerical argument. This is identical to the C function C. - $r = modf($x, $y); + $r = fmod($x, $y); It returns the remainder C<$r = $x - $n*$y>, where C<$n = trunc($x/$y)>. The C<$r> has the same sign as C<$x> and magnitude (absolute value) @@ -386,11 +403,13 @@ less than the magnitude of C<$y>. =item fopen -Use method C instead. +Use method C instead, or see L. =item fork -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for duplicating the current process, see L +and L if you are in Windows. =item fpathconf @@ -398,9 +417,9 @@ Retrieves the value of a configurable limit on a file or directory. This uses file descriptors such as those obtained by calling C. The following will determine the maximum length of the longest allowable -pathname on the filesystem which holds C. +pathname on the filesystem which holds C. - $fd = POSIX::open( "/tmp/foo", &POSIX::O_RDONLY ); + $fd = POSIX::open( "/var/foo", &POSIX::O_RDONLY ); $path_max = POSIX::fpathconf( $fd, &POSIX::_PC_PATH_MAX ); Returns C on failure. @@ -433,19 +452,19 @@ freopen() is C-specific, see L instead. Return the mantissa and exponent of a floating-point number. - ($mantissa, $exponent) = POSIX::frexp( 3.14 ); + ($mantissa, $exponent) = POSIX::frexp( 1.234e56 ); =item fscanf -fscanf() is C-specific--use <> and regular expressions instead. +fscanf() is C-specific, use EE and regular expressions instead. =item fseek -Use method C instead. +Use method C instead, or see L. =item fsetpos -Use method C instead. +Use method C instead, or seek L. =item fstat @@ -456,9 +475,13 @@ Perl's builtin C function. $fd = POSIX::open( "foo", &POSIX::O_RDONLY ); @stats = POSIX::fstat( $fd ); +=item fsync + +Use method C instead. + =item ftell -Use method C instead. +Use method C instead, or see L. =item fwrite @@ -471,97 +494,120 @@ see L. =item getchar -Returns one character from STDIN. +Returns one character from STDIN. Identical to Perl's C, +see L. =item getcwd Returns the name of the current working directory. +See also L. =item getegid -Returns the effective group id. +Returns the effective group identifier. Similar to Perl' s builtin +variable C<$(>, see L. =item getenv -Returns the value of the specified enironment variable. +Returns the value of the specified environment variable. The same information is available through the C<%ENV> array. =item geteuid -Returns the effective user id. +Returns the effective user identifier. Identical to Perl's builtin C<$E> +variable, see L. =item getgid -Returns the user's real group id. +Returns the user's real group identifier. Similar to Perl's builtin +variable C<$)>, see L. =item getgrgid -This is identical to Perl's builtin C function, -see L. +This is identical to Perl's builtin C function for +returning group entries by group identifiers, see +L. =item getgrnam -This is identical to Perl's builtin C function, -see L. +This is identical to Perl's builtin C function for +returning group entries by group names, see L. =item getgroups -Returns the ids of the user's supplementary groups. +Returns the ids of the user's supplementary groups. Similar to Perl's +builtin variable C<$)>, see L. =item getlogin -This is identical to Perl's builtin C function, -see L. +This is identical to Perl's builtin C function for +returning the user name associated with the current session, see +L. =item getpgrp -This is identical to Perl's builtin C function, -see L. +This is identical to Perl's builtin C function for +returning the process group identifier of the current process, see +L. =item getpid -Returns the process's id. +Returns the process identifier. Identical to Perl's builtin +variable C<$$>, see L. =item getppid -This is identical to Perl's builtin C function, -see L. +This is identical to Perl's builtin C function for +returning the process identifier of the parent process of the current +process , see L. =item getpwnam -This is identical to Perl's builtin C function, -see L. +This is identical to Perl's builtin C function for +returning user entries by user names, see L. =item getpwuid -This is identical to Perl's builtin C function, -see L. +This is identical to Perl's builtin C function for +returning user entries by user identifiers, see L. =item gets -Returns one line from C, similar to <>, also known -as the C functions, see L. +Returns one line from C, similar to EE, also known +as the C function, see L. + +B: if you have C programs that still use C, be very +afraid. The C function is a source of endless grief because +it has no buffer overrun checks. It should B be used. The +C function should be preferred instead. =item getuid -Returns the user's id. +Returns the user's identifier. Identical to Perl's builtin C<$E> variable, +see L. =item gmtime -This is identical to Perl's builtin C function, +This is identical to Perl's builtin C function for +converting seconds since the epoch to a date in Greenwich Mean Time, see L. =item isalnum -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +This is identical to the C function, except that it can apply to a +single character or to a whole string. Note that locale settings may +affect what characters are considered C. Does not work on +Unicode characters code point 256 or higher. Consider using regular +expressions and the C construct instead, or possibly +the C construct. =item isalpha -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +This is identical to the C function, except that it can apply to +a single character or to a whole string. Note that locale settings +may affect what characters are considered C. Does not work +on Unicode characters code point 256 or higher. Consider using regular +expressions and the C construct instead. =item isatty @@ -570,77 +616,109 @@ to a tty. Similar to the C<-t> operator, see L. =item iscntrl -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +This is identical to the C function, except that it can apply to +a single character or to a whole string. Note that locale settings +may affect what characters are considered C. Does not work +on Unicode characters code point 256 or higher. Consider using regular +expressions and the C construct instead. =item isdigit -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +This is identical to the C function, except that it can apply to +a single character or to a whole string. Note that locale settings +may affect what characters are considered C (unlikely, but +still possible). Does not work on Unicode characters code point 256 +or higher. Consider using regular expressions and the C +construct instead, or the C construct. =item isgraph -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +This is identical to the C function, except that it can apply to +a single character or to a whole string. Note that locale settings +may affect what characters are considered C. Does not work +on Unicode characters code point 256 or higher. Consider using regular +expressions and the C construct instead. =item islower -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +This is identical to the C function, except that it can apply to +a single character or to a whole string. Note that locale settings +may affect what characters are considered C. Does not work +on Unicode characters code point 256 or higher. Consider using regular +expressions and the C construct instead. Do B use +C. =item isprint -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +This is identical to the C function, except that it can apply to +a single character or to a whole string. Note that locale settings +may affect what characters are considered C. Does not work +on Unicode characters code point 256 or higher. Consider using regular +expressions and the C construct instead. =item ispunct -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +This is identical to the C function, except that it can apply to +a single character or to a whole string. Note that locale settings +may affect what characters are considered C. Does not work +on Unicode characters code point 256 or higher. Consider using regular +expressions and the C construct instead. =item isspace -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +This is identical to the C function, except that it can apply to +a single character or to a whole string. Note that locale settings +may affect what characters are considered C. Does not work +on Unicode characters code point 256 or higher. Consider using regular +expressions and the C construct instead, or the C +construct. (Note that C and C are slightly +different in that C can normally match a vertical tab, +while C does not.) =item isupper -This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +This is identical to the C function, except that it can apply to +a single character or to a whole string. Note that locale settings +may affect what characters are considered C. Does not work +on Unicode characters code point 256 or higher. Consider using regular +expressions and the C construct instead. Do B use +C. =item isxdigit This is identical to the C function, except that it can apply to a single -character or to a whole string. Consider using regular expressions and the -C construct instead. +character or to a whole string. Note that locale settings may affect what +characters are considered C (unlikely, but still possible). +Does not work on Unicode characters code point 256 or higher. +Consider using regular expressions and the C +construct instead, or simply C. =item kill -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function for sending +signals to processes (often to terminate them), see L. =item labs +(For returning absolute values of long integers.) labs() is C-specific, see L instead. =item ldexp -This is identical to the C function C. +This is identical to the C function C +for multiplying floating point numbers with powers of two. + + $x_quadrupled = POSIX::ldexp($x, 2); =item ldiv +(For computing dividends of long integers.) ldiv() is C-specific, use C and C instead. =item link -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for creating hard links into files, see L. =item localeconv @@ -673,7 +751,8 @@ Here is how to query the database for the B (Deutsch or German) locale. =item localtime -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function for +converting seconds since the epoch to a date see L. =item log @@ -691,7 +770,7 @@ You can also use or - sub log10 { log($_[0]) / 2.30258509299405 } + sub log10 { log($_[0]) / 2.30258509299405 } or @@ -718,14 +797,23 @@ malloc() is C-specific. Perl does memory management transparently. =item mblen This is identical to the C function C. +Perl does not have any support for the wide and multibyte +characters of the C standards, so this might be a rather +useless function. =item mbstowcs This is identical to the C function C. +Perl does not have any support for the wide and multibyte +characters of the C standards, so this might be a rather +useless function. =item mbtowc This is identical to the C function C. +Perl does not have any support for the wide and multibyte +characters of the C standards, so this might be a rather +useless function. =item memchr @@ -760,7 +848,8 @@ FIFO special files. if (mkfifo($path, $mode)) { .... Returns C on failure. The C<$mode> is similar to the -mode of C, see L. +mode of C, see L, though for C +you B specify the C<$mode>. =item mktime @@ -768,7 +857,7 @@ Convert date/time info to a calendar time. Synopsis: - mktime(sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = 0) + mktime(sec, min, hour, mday, mon, year, wday = 0, yday = 0, isdst = -1) The month (C), weekday (C), and yearday (C) begin at zero. I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The @@ -831,7 +920,7 @@ See also L. Open a directory for reading. - $dir = POSIX::opendir( "/tmp" ); + $dir = POSIX::opendir( "/var" ); @files = POSIX::readdir( $dir ); POSIX::closedir( $dir ); @@ -842,9 +931,9 @@ Returns C on failure. Retrieves the value of a configurable limit on a file or directory. The following will determine the maximum length of the longest allowable -pathname on the filesystem which holds C. +pathname on the filesystem which holds C. - $path_max = POSIX::pathconf( "/tmp", &POSIX::_PC_PATH_MAX ); + $path_max = POSIX::pathconf( "/var", &POSIX::_PC_PATH_MAX ); Returns C on failure. @@ -860,16 +949,16 @@ Returns C on failure. This is identical to the C function C, which outputs to the standard error stream the specified message followed by ": " and the current error string. Use the C function and the C<$!> -variable instead, see L and L. +variable instead, see L and L. =item pipe Create an interprocess channel. This returns file descriptors like those returned by C. - ($fd0, $fd1) = POSIX::pipe(); - POSIX::write( $fd0, "hello", 5 ); - POSIX::read( $fd1, $buf, 5 ); + my ($read, $write) = POSIX::pipe(); + POSIX::write( $write, "hello", 5 ); + POSIX::read( $read, $buf, 5 ); See also L. @@ -905,11 +994,11 @@ qsort() is C-specific, see L instead. =item raise Sends the specified signal to the current process. -See also L and the C<$$> in L. +See also L and the C<$$> in L. =item rand -rand() is non-portable, see L instead. +C is non-portable, see L instead. =item read @@ -959,12 +1048,17 @@ for removing (empty) directories, see L. =item scanf -scanf() is C-specific--use <> and regular expressions instead, +scanf() is C-specific, use EE and regular expressions instead, see L. =item setgid -Sets the real group id for this process. +Sets the real group identifier and the effective group identifier for +this process. Similar to assigning a value to the Perl's builtin +C<$)> variable, see L, except that the latter +will change only the real user identifier, and that the setgid() +uses only a single numeric argument, as opposed to a space-separated +list of numbers. =item setjmp @@ -991,7 +1085,7 @@ argument means 'query'.) The following will set the LC_CTYPE behaviour according to the locale environment variables (the second argument C<"">). -Please see your systems L documentation for the locale +Please see your systems C documentation for the locale environment variables' meaning or consult L. $loc = setlocale( LC_CTYPE, "" ); @@ -1005,29 +1099,66 @@ out which locales are available in your system. =item setpgid -This is similar to the C function C. +This is similar to the C function C for +setting the process group identifier of the current process. Returns C on failure. =item setsid -This is identical to the C function C. +This is identical to the C function C for +setting the session identifier of the current process. =item setuid -Sets the real user id for this process. +Sets the real user identifier and the effective user identifier for +this process. Similar to assigning a value to the Perl's builtin +C<$E> variable, see L, except that the latter +will change only the real user identifier. =item sigaction -Detailed signal management. This uses C objects for the -C and C arguments. Consult your system's C -manpage for details. +Detailed signal management. This uses C objects for +the C and C arguments (the oldaction can also be +just a hash reference). Consult your system's C manpage +for details, see also C. Synopsis: - sigaction(sig, action, oldaction = 0) + sigaction(signal, action, oldaction = 0) -Returns C on failure. +Returns C on failure. The C must be a number (like +SIGHUP), not a string (like "SIGHUP"), though Perl does try hard +to understand you. + +If you use the SA_SIGINFO flag, the signal handler will in addition to +the first argument, the signal name, also receive a second argument, a +hash reference, inside which are the following keys with the following +semantics, as defined by POSIX/SUSv3: + + signo the signal number + errno the error number + code if this is zero or less, the signal was sent by + a user process and the uid and pid make sense, + otherwise the signal was sent by the kernel + +The following are also defined by POSIX/SUSv3, but unfortunately +not very widely implemented: + + pid the process id generating the signal + uid the uid of the process id generating the signal + status exit value or signal for SIGCHLD + band band event for SIGPOLL + +A third argument is also passed to the handler, which contains a copy +of the raw binary contents of the siginfo structure: if a system has +some non-POSIX fields, this third argument is where to unpack() them +from. + +Note that not all siginfo values make sense simultaneously (some are +valid only for certain signals, for example), and not all values make +sense from Perl perspective, you should to consult your system's +C and possibly also C documentation. =item siglongjmp @@ -1078,18 +1209,22 @@ Returns C on failure. This is identical to Perl's builtin C function for returning the sine of the numerical argument, -see L. +see L. See also L. =item sinh This is identical to the C function C for returning the hyperbolic sine of the numerical argument. +See also L. =item sleep -This is identical to Perl's builtin C function -for suspending the execution of the current for process -for certain number of seconds, see L. +This is functionally identical to Perl's builtin C function +for suspending the execution of the current for process for certain +number of seconds, see L. There is one significant +difference, however: C returns the number of +B seconds, while the C returns the +number of slept seconds. =item sprintf @@ -1114,7 +1249,8 @@ see L. =item stat -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for returning information about files and directories. =item strcat @@ -1126,7 +1262,7 @@ strchr() is C-specific, see L instead. =item strcmp -strcmp() is C-specific, use C instead, see L. +strcmp() is C-specific, use C or C instead, see L. =item strcoll @@ -1141,12 +1277,13 @@ strcpy() is C-specific, use C<=> instead, see L. =item strcspn -strcspn() is C-specific, use regular expressions instead. +strcspn() is C-specific, use regular expressions instead, +see L. =item strerror Returns the error string for the specified errno. -Identical to the string form of the C<$!>, see L. +Identical to the string form of the C<$!>, see L. =item strftime @@ -1161,12 +1298,23 @@ I.e. January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The year (C) is given in years since 1900. I.e., the year 1995 is 95; the year 2001 is 101. Consult your system's C manpage for details about these and the other arguments. + If you want your code to be portable, your format (C) argument should use only the conversion specifiers defined by the ANSI C -standard. These are C. -The given arguments are made consistent -as though by calling C before calling your system's -C function, except that the C value is not affected. +standard (C89, to play safe). These are C. +But even then, the B of some of the conversion specifiers are +non-portable. For example, the specifiers C change according +to the locale settings of the user, and both how to set locales (the +locale names) and what output to expect are non-standard. +The specifier C changes according to the timezone settings of the +user and the timezone computation rules of the operating system. +The C specifier is notoriously unportable since the names of +timezones are non-standard. Sticking to the numeric specifiers is the +safest route. + +The given arguments are made consistent as though by calling +C before calling your system's C function, +except that the C value is not affected. The string for Tuesday, December 12, 1995. @@ -1191,7 +1339,8 @@ strncpy() is C-specific, use C<=> instead, see L. =item strpbrk -strpbrk() is C-specific, use regular expressions instead, see L. +strpbrk() is C-specific, use regular expressions instead, +see L. =item strrchr @@ -1224,8 +1373,8 @@ To parse a string $str as a floating point number use The second returned item and $! can be used to check for valid input: - if (($str eq '') || ($n_unparsed != 0) || !$!) { - die "Non-numeric input $str" . $! ? ": $!\n" : "\n"; + if (($str eq '') || ($n_unparsed != 0) || $!) { + die "Non-numeric input $str" . ($! ? ": $!\n" : "\n"); } When called in a scalar context strtod returns the parsed number. @@ -1303,12 +1452,12 @@ L. =item tan This is identical to the C function C, returning the -tangent of the numerical argument. +tangent of the numerical argument. See also L. =item tanh This is identical to the C function C, returning the -hyperbolic tangent of the numerical argument. +hyperbolic tangent of the numerical argument. See also L. =item tcdrain @@ -1327,14 +1476,14 @@ Returns C on failure. =item tcflush This is similar to the C function C for flushing -the I/O buffers of its argumeny stream. +the I/O buffers of its argument stream. Returns C on failure. =item tcgetpgrp This is identical to the C function C for returning the -process group id of the foreground process group of the controlling +process group identifier of the foreground process group of the controlling terminal. =item tcsendbreak @@ -1347,7 +1496,7 @@ Returns C on failure. =item tcsetpgrp This is similar to the C function C for setting the -process group id of the foreground process group of the controlling +process group identifier of the foreground process group of the controlling terminal. Returns C on failure. @@ -1372,7 +1521,7 @@ seconds. =item tmpfile -Use method C instead. +Use method C instead, or see L. =item tmpnam @@ -1380,7 +1529,9 @@ Returns a name for a temporary file. $tmpfile = POSIX::tmpnam(); -See also the L module. +For security reasons, which are probably detailed in your system's +documentation for the C library tmpnam() function, this interface +should not be used; instead see L. =item tolower @@ -1425,7 +1576,16 @@ see L. Get name of current operating system. - ($sysname, $nodename, $release, $version, $machine ) = POSIX::uname(); + ($sysname, $nodename, $release, $version, $machine) = POSIX::uname(); + +Note that the actual meanings of the various fields are not +that well standardized, do not expect any great portability. +The C<$sysname> might be the name of the operating system, +the C<$nodename> might be the name of the host, the C<$release> +might be the (major) release number of the operating system, +the C<$version> might be the (minor) release number of the +operating system, and the C<$machine> might be a hardware identifier. +Maybe. =item ungetc @@ -1464,16 +1624,22 @@ see L. Wait for a child process to change state. This is identical to Perl's builtin C function, see L. - $pid = POSIX::waitpid( -1, &POSIX::WNOHANG ); + $pid = POSIX::waitpid( -1, POSIX::WNOHANG ); print "status = ", ($? / 256), "\n"; =item wcstombs This is identical to the C function C. +Perl does not have any support for the wide and multibyte +characters of the C standards, so this might be a rather +useless function. =item wctomb This is identical to the C function C. +Perl does not have any support for the wide and multibyte +characters of the C standards, so this might be a rather +useless function. =item write @@ -1482,7 +1648,7 @@ calling C. $fd = POSIX::open( "foo", &POSIX::O_WRONLY ); $buf = "hello"; - $bytes = POSIX::write( $b, $buf, 5 ); + $bytes = POSIX::write( $fd, $buf, 5 ); Returns C on failure. @@ -1499,20 +1665,103 @@ See also L. =item new Creates a new C object which corresponds to the C -C. This object will be destroyed automatically when it is -no longer needed. The first parameter is the fully-qualified name of a sub -which is a signal-handler. The second parameter is a C -object, it defaults to the empty set. The third parameter contains the +C. This object will be destroyed automatically when +it is no longer needed. The first parameter is the handler, a sub +reference. The second parameter is a C object, it +defaults to the empty set. The third parameter contains the C, it defaults to 0. $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT); - $sigaction = POSIX::SigAction->new( 'main::handler', $sigset, &POSIX::SA_NOCLDSTOP ); + $sigaction = POSIX::SigAction->new( \&handler, $sigset, &POSIX::SA_NOCLDSTOP ); -This C object should be used with the C +This C object is intended for use with the C function. =back +=over 8 + +=item handler + +=item mask + +=item flags + +accessor functions to get/set the values of a SigAction object. + + $sigset = $sigaction->mask; + $sigaction->flags(&POSIX::SA_RESTART); + +=item safe + +accessor function for the "safe signals" flag of a SigAction object; see +L for general information on safe (a.k.a. "deferred") signals. If +you wish to handle a signal safely, use this accessor to set the "safe" flag +in the C object: + + $sigaction->safe(1); + +You may also examine the "safe" flag on the output action object which is +filled in when given as the third parameter to C: + + sigaction(SIGINT, $new_action, $old_action); + if ($old_action->safe) { + # previous SIGINT handler used safe signals + } + +=back + +=head2 POSIX::SigRt + +=over 8 + +=item %SIGRT + +A hash of the POSIX realtime signal handlers. It is an extension of +the standard %SIG, the $POSIX::SIGRT{SIGRTMIN} is roughly equivalent +to $SIG{SIGRTMIN}, but the right POSIX moves (see below) are made with +the POSIX::SigSet and POSIX::sigaction instead of accessing the %SIG. + +You can set the %POSIX::SIGRT elements to set the POSIX realtime +signal handlers, use C and C on the elements, and use +C on the C<%POSIX::SIGRT> to find out how many POSIX realtime +signals there are available (SIGRTMAX - SIGRTMIN + 1, the SIGRTMAX is +a valid POSIX realtime signal). + +Setting the %SIGRT elements is equivalent to calling this: + + sub new { + my ($rtsig, $handler, $flags) = @_; + my $sigset = POSIX::SigSet($rtsig); + my $sigact = POSIX::SigAction->new($handler, $sigset, $flags); + sigaction($rtsig, $sigact); + } + +The flags default to zero, if you want something different you can +either use C on $POSIX::SigRt::SIGACTION_FLAGS, or you can +derive from POSIX::SigRt and define your own C (the tied hash +STORE method of the %SIGRT calls C, +where the $rtsig ranges from zero to SIGRTMAX - SIGRTMIN + 1). + +Just as with any signal, you can use sigaction($rtsig, undef, $oa) to +retrieve the installed signal handler (or, rather, the signal action). + +B whether POSIX realtime signals really work in your system, or +whether Perl has been compiled so that it works with them, is outside +of this discussion. + +=item SIGRTMIN + +Return the minimum POSIX realtime signal number available, or C +if no POSIX realtime signals are available. + +=item SIGRTMAX + +Return the maximum POSIX realtime signal number available, or C +if no POSIX realtime signals are available. + +=back + =head2 POSIX::SigSet =over 8 @@ -1592,6 +1841,7 @@ Get terminal control attributes. Obtain the attributes for stdin. + $termios->getattr( 0 ) # Recommended for clarity. $termios->getattr() Obtain the attributes for stdout. @@ -1756,7 +2006,7 @@ _POSIX_ARG_MAX _POSIX_CHILD_MAX _POSIX_CHOWN_RESTRICTED _POSIX_JOB_CONTROL _POSI =item Constants -_SC_ARG_MAX _SC_CHILD_MAX _SC_CLK_TCK _SC_JOB_CONTROL _SC_NGROUPS_MAX _SC_OPEN_MAX _SC_SAVED_IDS _SC_STREAM_MAX _SC_TZNAME_MAX _SC_VERSION +_SC_ARG_MAX _SC_CHILD_MAX _SC_CLK_TCK _SC_JOB_CONTROL _SC_NGROUPS_MAX _SC_OPEN_MAX _SC_PAGESIZE _SC_SAVED_IDS _SC_STREAM_MAX _SC_TZNAME_MAX _SC_VERSION =back @@ -1905,13 +2155,56 @@ R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STDERR_FILENO W_OK X_ WNOHANG WUNTRACED +=over 16 + +=item WNOHANG + +Do not suspend the calling process until a child process +changes state but instead return immediately. + +=item WUNTRACED + +Catch stopped child processes. + +=back + =item Macros WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG WIFSTOPPED WSTOPSIG -=back +=over 16 + +=item WIFEXITED + +WIFEXITED($?) returns true if the child process exited normally +(C or by falling off the end of C) + +=item WEXITSTATUS + +WEXITSTATUS($?) returns the normal exit status of the child process +(only meaningful if WIFEXITED($?) is true) -=head1 CREATION +=item WIFSIGNALED -This document generated by ./mkposixman.PL version 19960129. +WIFSIGNALED($?) returns true if the child process terminated because +of a signal + +=item WTERMSIG + +WTERMSIG($?) returns the signal the child process terminated for +(only meaningful if WIFSIGNALED($?) is true) + +=item WIFSTOPPED + +WIFSTOPPED($?) returns true if the child process is currently stopped +(can happen only if you specified the WUNTRACED flag to waitpid()) + +=item WSTOPSIG + +WSTOPSIG($?) returns the signal the child process was stopped for +(only meaningful if WIFSTOPPED($?) is true) + +=back + +=back