X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=ext%2FPOSIX%2FPOSIX.pod;h=7263d0a62a090af23befb0133824b3d772ec23a1;hb=e27b5b51275a893e82bce85334679ee38d3d6bf8;hp=786df4c0b3d886113539237207820877565b9d4c;hpb=2ab27a20d8a21f3a809f28b58523b172cd26afd8;p=p5sagit%2Fp5-mst-13.2.git diff --git a/ext/POSIX/POSIX.pod b/ext/POSIX/POSIX.pod index 786df4c..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 @@ -115,8 +125,8 @@ 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 @@ -385,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) @@ -407,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. @@ -465,6 +475,10 @@ 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, or see L. @@ -495,7 +509,7 @@ 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 @@ -533,7 +547,7 @@ L. =item getpgrp This is identical to Perl's builtin C function for -returning the prcess group identifier of the current process, see +returning the process group identifier of the current process, see L. =item getpid @@ -580,15 +594,20 @@ 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, or possibly the C construct. +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 @@ -597,60 +616,82 @@ 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, or the C construct. +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. Do B use C. +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, 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.) +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. Do B use C. +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, or simply C. +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 @@ -729,7 +770,7 @@ You can also use or - sub log10 { log($_[0]) / 2.30258509299405 } + sub log10 { log($_[0]) / 2.30258509299405 } or @@ -757,21 +798,21 @@ malloc() is C-specific. Perl does memory management transparently. 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 +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 +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 +characters of the C standards, so this might be a rather useless function. =item memchr @@ -807,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 @@ -815,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 @@ -878,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 ); @@ -889,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. @@ -914,9 +956,9 @@ variable instead, see L and L. 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. @@ -1013,7 +1055,7 @@ see L. 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 +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. @@ -1076,15 +1118,47 @@ 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 @@ -1147,8 +1221,8 @@ See also 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 signifanct -difference, however: C returns the number or +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. @@ -1176,7 +1250,7 @@ see L. =item stat This is identical to Perl's builtin C function -for retutning information about files and directories. +for returning information about files and directories. =item strcat @@ -1224,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. @@ -1288,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. @@ -1391,7 +1476,7 @@ 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. @@ -1546,14 +1631,14 @@ builtin C function, see L. 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 +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 +characters of the C standards, so this might be a rather useless function. =item write @@ -1563,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. @@ -1580,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 @@ -1673,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.