X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=ext%2FPOSIX%2FPOSIX.pod;h=7263d0a62a090af23befb0133824b3d772ec23a1;hb=e27b5b51275a893e82bce85334679ee38d3d6bf8;hp=08300e4337b6e646281d02a39ae30ec31df1fe70;hpb=c529f79d594c53d3968d464c57ac24a21137dd09;p=p5sagit%2Fp5-mst-13.2.git diff --git a/ext/POSIX/POSIX.pod b/ext/POSIX/POSIX.pod index 08300e4..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 @@ -65,15 +69,25 @@ all. This could be construed to be a bug. =item _exit -This is identical to the C function C<_exit()>. +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. +This is identical to the C function C. It terminates the +process with a C signal unless caught by a signal handler or +if the handler does not return normally (it e.g. does a C). =item abs -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, returning +the absolute value of its numerical argument. =item access @@ -83,83 +97,117 @@ Determines the accessibility of a file. print "have read permission\n"; } -Returns C on failure. +Returns C on failure. Note: do not use C for +security purposes. Between the C call and the operation +you are preparing for the permissions might change: a classic +I. =item acos -This is identical to the C function C. +This is identical to the C function C, returning +the arcus cosine of its numerical argument. See also L. =item alarm -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +either for arming or disarming the C timer. =item asctime -This is identical to the C function C. +This is identical to the C function C. It returns +a string of the form + + "Fri Jun 2 18:22:13 2000\n\0" + +and it is called thusly + + $asctime = asctime($sec, $min, $hour, $mday, $mon, $year, + $wday, $yday, $isdst); + +The C<$mon> is zero-based: January equals C<0>. The C<$year> is +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. +This is identical to the C function C, returning +the arcus sine of its numerical argument. See also L. =item assert -Unimplemented. +Unimplemented, but you can use L and the L module +to achieve similar things. =item atan -This is identical to the C function C. +This is identical to the C function C, returning the +arcus tangent of its numerical argument. See also L. =item atan2 -This is identical to Perl's builtin C function. +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. See also L. =item atexit -atexit() is C-specific: use END {} instead. +atexit() is C-specific: use C instead, see L. =item atof -atof() is C-specific. +atof() is C-specific. Perl converts strings to numbers transparently. +If you need to force a scalar to a number, add a zero to it. =item atoi -atoi() is C-specific. +atoi() is C-specific. Perl converts strings to numbers transparently. +If you need to force a scalar to a number, add a zero to it. +If you need to have just the integer part, see L. =item atol -atol() is C-specific. +atol() is C-specific. Perl converts strings to numbers transparently. +If you need to force a scalar to a number, add a zero to it. +If you need to have just the integer part, see L. =item bsearch -bsearch() not supplied. +bsearch() not supplied. For doing binary search on wordlists, +see L. =item calloc -calloc() is C-specific. +calloc() is C-specific. Perl does memory management transparently. =item ceil -This is identical to the C function C. +This is identical to the C function C, returning the smallest +integer value greater than or equal to the given numerical argument. =item chdir -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, allowing +one to change the working (default) directory, see L. =item chmod -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, allowing +one to change file and directory permissions, see L. =item chown -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, allowing one +to change file and directory owners and groups, see L. =item clearerr -Use method C instead. +Use the method C instead, to reset the error +state (if any) and EOF state (if any) of the given stream. =item clock -This is identical to the C function C. +This is identical to the C function C, returning the +amount of spent processor time in microseconds. =item close @@ -171,17 +219,23 @@ C. Returns C on failure. +See also L. + =item closedir -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function for closing +a directory handle, see L. =item cos -This is identical to Perl's builtin C function. +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. +This is identical to the C function C, for returning +the hyperbolic cosine of its numeric argument. See also L. =item creat @@ -191,6 +245,8 @@ C. Use C to close the file. $fd = POSIX::creat( "foo", 0611 ); POSIX::close( $fd ); +See also L and its C flag. + =item ctermid Generates the path name for the controlling terminal. @@ -199,25 +255,30 @@ 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 -div() is C-specific. +div() is C-specific, use L on the usual C division and +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. @@ -226,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. @@ -239,57 +301,64 @@ Returns the value of errno. $errno = POSIX::errno(); +This identical to the numerical values of the C<$!>, see L. + =item execl -execl() is C-specific. +execl() is C-specific, see L. =item execle -execle() is C-specific. +execle() is C-specific, see L. =item execlp -execlp() is C-specific. +execlp() is C-specific, see L. =item execv -execv() is C-specific. +execv() is C-specific, see L. =item execve -execve() is C-specific. +execve() is C-specific, see L. =item execvp -execvp() is C-specific. +execvp() is C-specific, see L. =item exit -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function for exiting the +program, see L. =item exp -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function for +returning the exponent (I-based) of the numerical argument, +see L. =item fabs -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function for returning +the absolute value of the numerical argument, see L. =item fclose -Use method C instead. +Use method C instead, or see L. =item fcntl -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +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 @@ -298,38 +367,49 @@ 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. +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 -This is identical to the C function C. +This is identical to the C function C, returning the largest +integer value less than or equal to the numerical argument. =item fmod This is identical to the C function C. + $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) +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 @@ -337,54 +417,54 @@ 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. =item fprintf -fprintf() is C-specific--use printf instead. +fprintf() is C-specific, see L instead. =item fputc -fputc() is C-specific--use print instead. +fputc() is C-specific, see L instead. =item fputs -fputs() is C-specific--use print instead. +fputs() is C-specific, see L instead. =item fread -fread() is C-specific--use read instead. +fread() is C-specific, see L instead. =item free -free() is C-specific. +free() is C-specific. Perl does memory management transparently. =item freopen -freopen() is C-specific--use open instead. +freopen() is C-specific, see L instead. =item frexp 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 @@ -395,176 +475,257 @@ 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 -fwrite() is C-specific--use print instead. +fwrite() is C-specific, see L instead. =item getc -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +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. +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. +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. +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. +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. +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. +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. +This is identical to Perl's builtin C function for +returning user entries by user identifiers, see L. =item gets -Returns one line from STDIN. +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. +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. +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 Returns a boolean indicating whether the specified filehandle is connected -to a tty. +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. +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. +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. +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. +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. +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. +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. +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. +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. +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 -labs() is C-specific, use abs instead. +(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 -ldiv() is C-specific, use / and int instead. +(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 Get numeric formatting information. Returns a reference to a hash containing the current locale formatting values. -The database for the B (Deutsch or German) locale. +Here is how to query the database for the B (Deutsch or German) locale. $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" ); print "Locale = $loc\n"; @@ -590,19 +751,34 @@ 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 -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +returning the natural (I-based) logarithm of the numerical argument, +see L. =item log10 -This is identical to the C function C. +This is identical to the C function C, +returning the 10-base logarithm of the numerical argument. +You can also use + + sub log10 { log($_[0]) / log(10) } + +or + + sub log10 { log($_[0]) / 2.30258509299405 } + +or + + sub log10 { log($_[0]) * 0.434294481903252 } =item longjmp -longjmp() is C-specific: use die instead. +longjmp() is C-specific: use L instead. =item lseek @@ -616,49 +792,64 @@ Returns C on failure. =item malloc -malloc() is C-specific. +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 -memchr() is C-specific, use index() instead. +memchr() is C-specific, see L instead. =item memcmp -memcmp() is C-specific, use eq instead. +memcmp() is C-specific, use C instead, see L. =item memcpy -memcpy() is C-specific, use = instead. +memcpy() is C-specific, use C<=>, see L, or see L. =item memmove -memmove() is C-specific, use = instead. +memmove() is C-specific, use C<=>, see L, or see L. =item memset -memset() is C-specific, use x instead. +memset() is C-specific, use C instead, see L. =item mkdir -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for creating directories, see L. =item mkfifo -This is similar to the C function C. +This is similar to the C function C for creating +FIFO special files. -Returns C on failure. + if (mkfifo($path, $mode)) { .... + +Returns C on failure. The C<$mode> is similar to the +mode of C, see L, though for C +you B specify the C<$mode>. =item mktime @@ -666,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 @@ -689,13 +880,16 @@ Return the integral and fractional parts of a floating-point number. =item nice -This is similar to the C function C. +This is similar to the C function C, for changing +the scheduling preference of the current process. Positive +arguments mean more polite process, negative values more +needy process. Normal user processes can only be more polite. Returns C on failure. =item offsetof -offsetof() is C-specific. +offsetof() is C-specific, you probably want to see L instead. =item open @@ -720,11 +914,13 @@ Create a new file with mode 0640. Set up the file for writing. Returns C on failure. +See also L. + =item opendir Open a directory for reading. - $dir = POSIX::opendir( "/tmp" ); + $dir = POSIX::opendir( "/var" ); @files = POSIX::readdir( $dir ); POSIX::closedir( $dir ); @@ -735,64 +931,74 @@ 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. =item pause -This is similar to the C function C. +This is similar to the C function C, which suspends +the execution of the current process until a signal is received. Returns C on failure. =item perror -This is identical to the C function C. +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. =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. =item pow -Computes $x raised to the power $exponent. +Computes C<$x> raised to the power C<$exponent>. $ret = POSIX::pow( $x, $exponent ); +You can also use the C<**> operator, see L. + =item printf -Prints the specified arguments to STDOUT. +Formats and prints the specified arguments to STDOUT. +See also L. =item putc -putc() is C-specific--use print instead. +putc() is C-specific, see L instead. =item putchar -putchar() is C-specific--use print instead. +putchar() is C-specific, see L instead. =item puts -puts() is C-specific--use print instead. +puts() is C-specific, see L instead. =item qsort -qsort() is C-specific, use sort instead. +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. =item rand -rand() is non-portable, use Perl's rand instead. +C is non-portable, see L instead. =item read @@ -805,21 +1011,26 @@ read then Perl will extend it to make room for the request. Returns C on failure. +See also L. + =item readdir -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for reading directory entries, see L. =item realloc -realloc() is C-specific. +realloc() is C-specific. Perl does memory management transparently. =item remove -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for removing files, see L. =item rename -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for renaming files, see L. =item rewind @@ -827,23 +1038,32 @@ Seeks to the beginning of the file. =item rewinddir -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function for +rewinding directory entry streams, see L. =item rmdir -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +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 -setjmp() is C-specific: use eval {} instead. +C is C-specific: use C instead, +see L. =item setlocale @@ -865,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, "" ); @@ -879,33 +1099,70 @@ 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 -siglongjmp() is C-specific: use die instead. +siglongjmp() is C-specific: use L instead. =item sigpending @@ -933,7 +1190,8 @@ Returns C on failure. =item sigsetjmp -sigsetjmp() is C-specific: use eval {} instead. +C is C-specific: use C instead, +see L. =item sigsuspend @@ -949,63 +1207,83 @@ Returns C on failure. =item sin -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for returning the sine of the numerical argument, +see L. See also L. =item sinh -This is identical to the C function C. +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. +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 -This is identical to Perl's builtin C function. +This is similar to Perl's builtin C function +for returning a string that has the arguments formatted as requested, +see L. =item sqrt This is identical to Perl's builtin C function. +for returning the square root of the numerical argument, +see L. =item srand -srand(). +Give a seed the pseudorandom number generator, see L. =item sscanf -sscanf() is C-specific--use regular expressions instead. +sscanf() is C-specific, use regular expressions instead, +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 -strcat() is C-specific, use .= instead. +strcat() is C-specific, use C<.=> instead, see L. =item strchr -strchr() is C-specific, use index() instead. +strchr() is C-specific, see L instead. =item strcmp -strcmp() is C-specific, use eq instead. +strcmp() is C-specific, use C or C instead, see L. =item strcoll -This is identical to the C function C. +This is identical to the C function C +for collating (comparing) strings transformed using +the C function. Not really needed since +Perl can do this transparently, see L. =item strcpy -strcpy() is C-specific, use = instead. +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. =item strftime @@ -1020,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. @@ -1034,39 +1323,38 @@ The string for Tuesday, December 12, 1995. =item strlen -strlen() is C-specific, use length instead. +strlen() is C-specific, use C instead, see L. =item strncat -strncat() is C-specific, use .= instead. +strncat() is C-specific, use C<.=> instead, see L. =item strncmp -strncmp() is C-specific, use eq instead. +strncmp() is C-specific, use C instead, see L. =item strncpy -strncpy() is C-specific, use = instead. - -=item stroul - -stroul() is C-specific. +strncpy() is C-specific, use C<=> instead, see L. =item strpbrk -strpbrk() is C-specific. +strpbrk() is C-specific, use regular expressions instead, +see L. =item strrchr -strrchr() is C-specific, use rindex() instead. +strrchr() is C-specific, see L instead. =item strspn -strspn() is C-specific. +strspn() is C-specific, use regular expressions instead, +see L. =item strstr -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +see L. =item strtod @@ -1085,15 +1373,16 @@ 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. =item strtok -strtok() is C-specific. +strtok() is C-specific, use regular expressions instead, see +L, or L. =item strtol @@ -1127,12 +1416,12 @@ When called in a scalar context strtol returns the parsed number. =item strtoul -String to unsigned (long) integer translation. strtoul is identical -to strtol except that strtoul only parses unsigned integers. See -I for details. +String to unsigned (long) integer translation. strtoul() is identical +to strtol() except that strtoul() only parses unsigned integers. See +L for details. -Note: Some vendors supply strtod and strtol but not strtoul. -Other vendors that do suply strtoul parse "-1" as a valid value. +Note: Some vendors supply strtod() and strtol() but not strtoul(). +Other vendors that do supply strtoul() parse "-1" as a valid value. =item strxfrm @@ -1140,6 +1429,11 @@ String transformation. Returns the transformed string. $dst = POSIX::strxfrm( $src ); +Used in conjunction with the C function, see L. + +Not really needed since Perl can do this transparently, see +L. + =item sysconf Retrieves values of system configurable variables. @@ -1152,53 +1446,66 @@ Returns C on failure. =item system -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, see +L. =item tan -This is identical to the C function C. +This is identical to the C function C, returning the +tangent of the numerical argument. See also L. =item tanh -This is identical to the C function C. +This is identical to the C function C, returning the +hyperbolic tangent of the numerical argument. See also L. =item tcdrain -This is similar to the C function C. +This is similar to the C function C for draining +the output queue of its argument stream. Returns C on failure. =item tcflow -This is similar to the C function C. +This is similar to the C function C for controlling +the flow of its argument stream. Returns C on failure. =item tcflush -This is similar to the C function C. +This is similar to the C function C for flushing +the I/O buffers of its argument stream. Returns C on failure. =item tcgetpgrp -This is identical to the C function C. +This is identical to the C function C for returning the +process group identifier of the foreground process group of the controlling +terminal. =item tcsendbreak -This is similar to the C function C. +This is similar to the C function C for sending +a break on its argument stream. Returns C on failure. =item tcsetpgrp -This is similar to the C function C. +This is similar to the C function C for setting the +process group identifier of the foreground process group of the controlling +terminal. Returns C on failure. =item time -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for returning the number of seconds since the epoch +(whatever it is for the system), see L. =item times @@ -1214,7 +1521,7 @@ seconds. =item tmpfile -Use method C instead. +Use method C instead, or see L. =item tmpnam @@ -1222,17 +1529,28 @@ Returns a name for a temporary file. $tmpfile = POSIX::tmpnam(); +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 -This is identical to Perl's builtin C function. +This is identical to the C function, except that it can apply to a single +character or to a whole string. Consider using the C function, +see L, or the equivalent C<\L> operator inside doublequotish +strings. =item toupper -This is identical to Perl's builtin C function. +This is identical to the C function, except that it can apply to a single +character or to a whole string. Consider using the C function, +see L, or the equivalent C<\U> operator inside doublequotish +strings. =item ttyname -This is identical to the C function C. +This is identical to the C function C for returning the +name of the current terminal. =item tzname @@ -1243,17 +1561,31 @@ Retrieves the time conversion information from the C variable. =item tzset -This is identical to the C function C. +This is identical to the C function C for setting +the current timezone based on the environment variable C, +to be used by C, C, C, and C +functions. =item umask -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for setting (and querying) the file creation permission mask, +see L. =item uname 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 @@ -1261,43 +1593,53 @@ Use method C instead. =item unlink -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for removing files, see L. =item utime -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function +for changing the time stamps of files and directories, +see L. =item vfprintf -vfprintf() is C-specific. +vfprintf() is C-specific, see L instead. =item vprintf -vprintf() is C-specific. +vprintf() is C-specific, see L instead. =item vsprintf -vsprintf() is C-specific. +vsprintf() is C-specific, see L instead. =item wait -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +see L. =item waitpid Wait for a child process to change state. This is identical to Perl's -builtin C function. +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 @@ -1306,10 +1648,12 @@ 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. +See also L. + =back =head1 CLASSES @@ -1321,20 +1665,103 @@ Returns C on failure. =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 @@ -1414,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. @@ -1578,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 @@ -1715,7 +2143,7 @@ CLK_TCK CLOCKS_PER_SEC =item Constants -R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STRERR_FILENO W_OK X_OK +R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STDERR_FILENO W_OK X_OK =back @@ -1727,13 +2155,56 @@ R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STRERR_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 -=head1 CREATION +WIFEXITED($?) returns true if the child process exited normally +(C or by falling off the end of C) -This document generated by ./mkposixman.PL version 19960129. +=item WEXITSTATUS + +WEXITSTATUS($?) returns the normal exit status of the child process +(only meaningful if WIFEXITED($?) is true) + +=item WIFSIGNALED + +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