X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=ext%2FPOSIX%2FPOSIX.pod;h=598464d3fc6ce13980b91d9cf7f01470cfbf9cb6;hb=117206bb8d8e2af3a310913a670836bd2f8023df;hp=286df40ec1580e09f1dca862ad6631480b6020ff;hpb=0111df86b68202837d8ca044a27bbc00d7895fb1;p=p5sagit%2Fp5-mst-13.2.git diff --git a/ext/POSIX/POSIX.pod b/ext/POSIX/POSIX.pod index 286df40..598464d 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 @@ -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 @@ -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. @@ -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 @@ -1082,9 +1123,11 @@ manpage for details. 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. =item siglongjmp @@ -1224,12 +1267,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. @@ -1391,7 +1445,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. @@ -1587,13 +1641,45 @@ 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( \&main::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::SigSet =over 8