From b0b407d10583e9cf91fd5f5f7c28712d2c30c70e Mon Sep 17 00:00:00 2001 From: Jarkko Hietaniemi Date: Fri, 30 Jun 2000 18:28:37 +0000 Subject: [PATCH] Elaborate POSIX.pod. Still needs work. p4raw-id: //depot/cfgperl@6296 --- ext/POSIX/POSIX.pod | 488 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 333 insertions(+), 155 deletions(-) diff --git a/ext/POSIX/POSIX.pod b/ext/POSIX/POSIX.pod index 186d72e..c13e839 100644 --- a/ext/POSIX/POSIX.pod +++ b/ext/POSIX/POSIX.pod @@ -65,15 +65,19 @@ 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. =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 +87,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. =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>. The C<$wday>, C<$yday>, and C<$isdst> +default to zero (and the first two are usually ignored anyway). =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. =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. =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. =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 L 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 +209,22 @@ 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. =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. =item creat @@ -191,6 +234,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. @@ -213,7 +258,8 @@ This is identical to the C function C. =item div -div() is C-specific. +div() is C-specific, use L on the usual C division and +the modulus C<%>. =item dup @@ -239,41 +285,47 @@ 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 @@ -281,7 +333,8 @@ Use method C instead. =item fcntl -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +see L. =item fdopen @@ -309,7 +362,8 @@ Use method C instead. =item fgets -Use method C instead. +Use method C instead. Similar to <>, also known +as L. =item fileno @@ -317,12 +371,19 @@ Use method C instead. =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 = modf($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. @@ -346,27 +407,27 @@ 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 @@ -401,11 +462,12 @@ Use method C instead. =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 @@ -422,6 +484,7 @@ Returns the effective group id. =item getenv Returns the value of the specified enironment variable. +The same information is available through the C<%ENV> array. =item geteuid @@ -433,11 +496,13 @@ Returns the user's real group id. =item getgrgid -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +see L. =item getgrnam -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +see L. =item getgroups @@ -445,11 +510,13 @@ Returns the ids of the user's supplementary groups. =item getlogin -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +see L. =item getpgrp -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +see L. =item getpid @@ -457,19 +524,23 @@ Returns the process's id. =item getppid -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +see L. =item getpwnam -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +see L. =item getpwuid -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +see L. =item gets -Returns one line from STDIN. +Returns one line from C, similar to <>, also known +as the C functions, see L. =item getuid @@ -477,67 +548,79 @@ Returns the user's id. =item gmtime -This is identical to Perl's builtin C function. +This is identical to Perl's builtin C function, +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. +character or to a whole string. Consider using regular expressions and the +C construct instead. =item isalpha 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. 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. +character or to a whole string. 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. +character or to a whole string. Consider using regular expressions and the +C construct instead. =item isgraph 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. 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. +character or to a whole string. Consider using regular expressions and the +C construct instead. =item isprint 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. 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. +character or to a whole string. 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. +character or to a whole string. Consider using regular expressions and the +C construct instead. =item isupper 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. Consider using regular expressions and the +C construct instead. =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. Consider using regular expressions and the +C construct instead. =item kill @@ -545,7 +628,7 @@ This is identical to Perl's builtin C function. =item labs -labs() is C-specific, use abs instead. +labs() is C-specific, see L instead. =item ldexp @@ -553,7 +636,7 @@ This is identical to the C function C. =item ldiv -ldiv() is C-specific, use / and int instead. +ldiv() is C-specific, use C and C instead. =item link @@ -564,7 +647,7 @@ This is identical to Perl's builtin C function. 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"; @@ -594,15 +677,29 @@ This is identical to Perl's builtin C function. =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,7 +713,7 @@ Returns C on failure. =item malloc -malloc() is C-specific. +malloc() is C-specific. Perl does memory management transparently. =item mblen @@ -632,33 +729,38 @@ This is identical to the C function C. =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. =item mktime @@ -689,13 +791,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,6 +825,8 @@ 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. @@ -743,13 +850,17 @@ 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 @@ -760,39 +871,45 @@ returned by C. POSIX::write( $fd0, "hello", 5 ); POSIX::read( $fd1, $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. +rand() is non-portable, see L instead. =item read @@ -805,21 +922,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,15 +949,18 @@ 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 <> and regular expressions instead, +see L. =item setgid @@ -843,7 +968,8 @@ Sets the real group id for this process. =item setjmp -setjmp() is C-specific: use eval {} instead. +C is C-specific: use C instead, +see L. =item setlocale @@ -905,7 +1031,7 @@ Returns C on failure. =item siglongjmp -siglongjmp() is C-specific: use die instead. +siglongjmp() is C-specific: use L instead. =item sigpending @@ -933,7 +1059,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,31 +1076,41 @@ 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. =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. =item sleep -This is identical to Perl's builtin C function. +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. =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 @@ -981,23 +1118,26 @@ This is identical to Perl's builtin C function. =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 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 @@ -1006,6 +1146,7 @@ strcspn() is C-specific, use regular expressions instead. =item strerror Returns the error string for the specified errno. +Identical to the string form of the C<$!>, see L. =item strftime @@ -1034,39 +1175,37 @@ 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 @@ -1093,7 +1232,8 @@ 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 +1267,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 +1280,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 +1297,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. =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. =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 argumeny 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 id 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 id 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 @@ -1222,17 +1380,26 @@ Returns a name for a temporary file. $tmpfile = POSIX::tmpnam(); +See also the L module. + =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,11 +1410,16 @@ 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 @@ -1261,32 +1433,36 @@ 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 ); print "status = ", ($? / 256), "\n"; @@ -1310,6 +1486,8 @@ calling C. Returns C on failure. +See also L. + =back =head1 CLASSES -- 2.7.4