Commit | Line | Data |
---|---|---|
37120919 AD |
1 | =head1 NAME |
2 | ||
3 | POSIX - Perl interface to IEEE Std 1003.1 | |
4 | ||
cb1a09d0 AD |
5 | =head1 SYNOPSIS |
6 | ||
a17b2d91 | 7 | use POSIX (); |
cb1a09d0 AD |
8 | use POSIX qw(setsid); |
9 | use POSIX qw(:errno_h :fcntl_h); | |
10 | ||
11 | printf "EINTR is %d\n", EINTR; | |
12 | ||
13 | $sess_id = POSIX::setsid(); | |
14 | ||
15 | $fd = POSIX::open($path, O_CREAT|O_EXCL|O_WRONLY, 0644); | |
16 | # note: that's a filedescriptor, *NOT* a filehandle | |
17 | ||
37120919 AD |
18 | =head1 DESCRIPTION |
19 | ||
20 | The POSIX module permits you to access all (or nearly all) the standard | |
21 | POSIX 1003.1 identifiers. Many of these identifiers have been given Perl-ish | |
90b1bb76 MS |
22 | interfaces. |
23 | ||
37120919 AD |
24 | This document gives a condensed list of the features available in the POSIX |
25 | module. Consult your operating system's manpages for general information on | |
26 | most features. Consult L<perlfunc> for functions which are noted as being | |
dc416353 | 27 | identical or almost identical to Perl's builtin functions. |
37120919 AD |
28 | |
29 | The first section describes POSIX functions from the 1003.1 specification. | |
30 | The second section describes some classes for signal objects, TTY objects, | |
31 | and other miscellaneous objects. The remaining sections list various | |
32 | constants and macros in an organization which roughly follows IEEE Std | |
33 | 1003.1b-1993. | |
34 | ||
3609ea0d | 35 | =head1 CAVEATS |
37120919 | 36 | |
ea660a4b AP |
37 | I<Everything is exported by default> (with a handful of exceptions). |
38 | This is an unfortunate backwards compatibility feature and its use is | |
39 | B<strongly L<discouraged|perlpolicy/discouraged>>. | |
40 | You should either prevent the exporting (by saying S<C<use POSIX ();>>, | |
41 | as usual) and then use fully qualified names (e.g. C<POSIX::SEEK_END>), | |
42 | or give an explicit import list. | |
43 | If you do neither and opt for the default (as in S<C<use POSIX;>>), you | |
44 | will import I<hundreds and hundreds> of symbols into your namespace. | |
45 | ||
37120919 AD |
46 | A few functions are not implemented because they are C specific. If you |
47 | attempt to call these, they will print a message telling you that they | |
41cd218c KW |
48 | aren't implemented, and suggest using the Perl equivalent, should one |
49 | exist. For example, trying to access the C<setjmp()> call will elicit the | |
50 | message "C<setjmp() is C-specific: use eval {} instead>". | |
37120919 AD |
51 | |
52 | Furthermore, some evil vendors will claim 1003.1 compliance, but in fact | |
53 | are not so: they will not pass the PCTS (POSIX Compliance Test Suites). | |
41cd218c KW |
54 | For example, one vendor may not define C<EDEADLK>, or the semantics of the |
55 | errno values set by C<open(2)> might not be quite right. Perl does not | |
37120919 AD |
56 | attempt to verify POSIX compliance. That means you can currently |
57 | successfully say "use POSIX", and then later in your program you find | |
41cd218c | 58 | that your vendor has been lax and there's no usable C<ICANON> macro after |
37120919 AD |
59 | all. This could be construed to be a bug. |
60 | ||
61 | =head1 FUNCTIONS | |
62 | ||
63 | =over 8 | |
64 | ||
41cd218c | 65 | =item C<_exit> |
37120919 | 66 | |
4755096e GS |
67 | This is identical to the C function C<_exit()>. It exits the program |
68 | immediately which means among other things buffered I/O is B<not> flushed. | |
37120919 | 69 | |
15978375 JH |
70 | Note that when using threads and in Linux this is B<not> a good way to |
71 | exit a thread because in Linux processes and threads are kind of the | |
72 | same thing (Note: while this is the situation in early 2003 there are | |
73 | projects under way to have threads with more POSIXly semantics in Linux). | |
74 | If you want not to return from a thread, detach the thread. | |
75 | ||
41cd218c | 76 | =item C<abort> |
37120919 | 77 | |
4755096e GS |
78 | This is identical to the C function C<abort()>. It terminates the |
79 | process with a C<SIGABRT> signal unless caught by a signal handler or | |
80 | if the handler does not return normally (it e.g. does a C<longjmp>). | |
37120919 | 81 | |
41cd218c | 82 | =item C<abs> |
37120919 | 83 | |
bda53d3e JK |
84 | This is identical to Perl's builtin C<abs()> function, returning the absolute |
85 | value of its numerical argument (except that C<POSIX::abs()> must be provided | |
86 | an explicit value (rather than relying on an implicit C<$_>): | |
87 | ||
88 | $absolute_value = POSIX::abs(42); # good | |
89 | ||
90 | $absolute_value = POSIX::abs(); # throws exception | |
37120919 | 91 | |
41cd218c | 92 | =item C<access> |
37120919 AD |
93 | |
94 | Determines the accessibility of a file. | |
95 | ||
96 | if( POSIX::access( "/", &POSIX::R_OK ) ){ | |
97 | print "have read permission\n"; | |
98 | } | |
99 | ||
4755096e GS |
100 | Returns C<undef> on failure. Note: do not use C<access()> for |
101 | security purposes. Between the C<access()> call and the operation | |
102 | you are preparing for the permissions might change: a classic | |
103 | I<race condition>. | |
37120919 | 104 | |
41cd218c | 105 | =item C<acos> |
37120919 | 106 | |
4755096e | 107 | This is identical to the C function C<acos()>, returning |
c2e66d9e | 108 | the arcus cosine of its numerical argument. See also L<Math::Trig>. |
37120919 | 109 | |
9d233e12 JH |
110 | =item C<acosh> |
111 | ||
4d0de388 | 112 | This is identical to the C function C<acosh()>, returning the |
9d233e12 JH |
113 | hyperbolic arcus cosine of its numerical argument [C99]. See also |
114 | L<Math::Trig>. | |
115 | ||
41cd218c | 116 | =item C<alarm> |
37120919 | 117 | |
bda53d3e JK |
118 | This is identical to Perl's builtin C<alarm()> function, either for arming or |
119 | disarming the C<SIGARLM> timer, except that C<POSIX::alarm()> must be provided | |
120 | an explicit value (rather than relying on an implicit C<$_>): | |
121 | ||
122 | POSIX::alarm(3) # good | |
123 | ||
124 | POSIX::alarm() # throws exception | |
37120919 | 125 | |
41cd218c | 126 | =item C<asctime> |
37120919 | 127 | |
4755096e GS |
128 | This is identical to the C function C<asctime()>. It returns |
129 | a string of the form | |
130 | ||
131 | "Fri Jun 2 18:22:13 2000\n\0" | |
132 | ||
133 | and it is called thusly | |
134 | ||
b70c169c FC |
135 | $asctime = asctime($sec, $min, $hour, $mday, $mon, |
136 | $year, $wday, $yday, $isdst); | |
4755096e GS |
137 | |
138 | The C<$mon> is zero-based: January equals C<0>. The C<$year> is | |
c1646883 RGS |
139 | 1900-based: 2001 equals C<101>. C<$wday> and C<$yday> default to zero |
140 | (and are usually ignored anyway), and C<$isdst> defaults to -1. | |
37120919 | 141 | |
41cd218c | 142 | =item C<asin> |
37120919 | 143 | |
4755096e | 144 | This is identical to the C function C<asin()>, returning |
c2e66d9e | 145 | the arcus sine of its numerical argument. See also L<Math::Trig>. |
37120919 | 146 | |
9d233e12 JH |
147 | =item C<asinh> |
148 | ||
4d0de388 | 149 | This is identical to the C function C<asinh()>, returning the |
9d233e12 JH |
150 | hyperbolic arcus sine of its numerical argument [C99]. See also |
151 | L<Math::Trig>. | |
152 | ||
41cd218c | 153 | =item C<assert> |
37120919 | 154 | |
4755096e GS |
155 | Unimplemented, but you can use L<perlfunc/die> and the L<Carp> module |
156 | to achieve similar things. | |
37120919 | 157 | |
41cd218c | 158 | =item C<atan> |
37120919 | 159 | |
4755096e | 160 | This is identical to the C function C<atan()>, returning the |
c2e66d9e | 161 | arcus tangent of its numerical argument. See also L<Math::Trig>. |
37120919 | 162 | |
9d233e12 JH |
163 | =item C<atanh> |
164 | ||
4d0de388 | 165 | This is identical to the C function C<atanh()>, returning the |
9d233e12 JH |
166 | hyperbolic arcus tangent of its numerical argument [C99]. See also |
167 | L<Math::Trig>. | |
168 | ||
41cd218c | 169 | =item C<atan2> |
37120919 | 170 | |
4755096e GS |
171 | This is identical to Perl's builtin C<atan2()> function, returning |
172 | the arcus tangent defined by its two numerical arguments, the I<y> | |
c2e66d9e | 173 | coordinate and the I<x> coordinate. See also L<Math::Trig>. |
37120919 | 174 | |
41cd218c | 175 | =item C<atexit> |
37120919 | 176 | |
4d0de388 | 177 | Not implemented. C<atexit()> is C-specific: use C<END {}> instead, see L<perlmod>. |
37120919 | 178 | |
41cd218c | 179 | =item C<atof> |
37120919 | 180 | |
4d0de388 | 181 | Not implemented. C<atof()> is C-specific. Perl converts strings to numbers transparently. |
4755096e | 182 | If you need to force a scalar to a number, add a zero to it. |
37120919 | 183 | |
41cd218c | 184 | =item C<atoi> |
37120919 | 185 | |
4d0de388 | 186 | Not implemented. C<atoi()> is C-specific. Perl converts strings to numbers transparently. |
4755096e GS |
187 | If you need to force a scalar to a number, add a zero to it. |
188 | If you need to have just the integer part, see L<perlfunc/int>. | |
37120919 | 189 | |
41cd218c | 190 | =item C<atol> |
37120919 | 191 | |
4d0de388 | 192 | Not implemented. C<atol()> is C-specific. Perl converts strings to numbers transparently. |
4755096e GS |
193 | If you need to force a scalar to a number, add a zero to it. |
194 | If you need to have just the integer part, see L<perlfunc/int>. | |
37120919 | 195 | |
41cd218c | 196 | =item C<bsearch> |
37120919 | 197 | |
41cd218c | 198 | C<bsearch()> not supplied. For doing binary search on wordlists, |
4755096e | 199 | see L<Search::Dict>. |
37120919 | 200 | |
41cd218c | 201 | =item C<calloc> |
37120919 | 202 | |
4d0de388 | 203 | Not implemented. C<calloc()> is C-specific. Perl does memory management transparently. |
37120919 | 204 | |
9d233e12 JH |
205 | =item C<cbrt> |
206 | ||
207 | The cube root [C99]. | |
208 | ||
41cd218c | 209 | =item C<ceil> |
37120919 | 210 | |
4755096e GS |
211 | This is identical to the C function C<ceil()>, returning the smallest |
212 | integer value greater than or equal to the given numerical argument. | |
37120919 | 213 | |
41cd218c | 214 | =item C<chdir> |
37120919 | 215 | |
bda53d3e JK |
216 | This is identical to Perl's builtin C<chdir()> function, allowing one to |
217 | change the working (default) directory -- see L<perlfunc/chdir> -- with the | |
218 | exception that C<POSIX::chdir()> must be provided an explicit value (rather | |
219 | than relying on an implicit C<$_>): | |
220 | ||
221 | $rv = POSIX::chdir('path/to/dir'); # good | |
222 | ||
223 | $rv = POSIX::chdir(); # throws exception | |
37120919 | 224 | |
41cd218c | 225 | =item C<chmod> |
37120919 | 226 | |
4755096e | 227 | This is identical to Perl's builtin C<chmod()> function, allowing |
bda53d3e JK |
228 | one to change file and directory permissions -- see L<perlfunc/chmod> -- with |
229 | the exception that C<POSIX::chmod()> can only change one file at a time | |
230 | (rather than a list of files): | |
231 | ||
232 | $c = chmod 0664, $file1, $file2; # good | |
233 | ||
234 | $c = POSIX::chmod 0664, $file1; # throws exception | |
235 | ||
236 | $c = POSIX::chmod 0664, $file1, $file2; # throws exception | |
37120919 | 237 | |
c6f0b8ca TC |
238 | As with the built-in C<chmod()>, C<$file> may be a filename or a file |
239 | handle. | |
240 | ||
41cd218c | 241 | =item C<chown> |
37120919 | 242 | |
4755096e GS |
243 | This is identical to Perl's builtin C<chown()> function, allowing one |
244 | to change file and directory owners and groups, see L<perlfunc/chown>. | |
37120919 | 245 | |
41cd218c | 246 | =item C<clearerr> |
37120919 | 247 | |
4d0de388 | 248 | Not implemented. Use the method C<IO::Handle::clearerr()> instead, to reset the error |
4755096e | 249 | state (if any) and EOF state (if any) of the given stream. |
37120919 | 250 | |
41cd218c | 251 | =item C<clock> |
37120919 | 252 | |
4755096e GS |
253 | This is identical to the C function C<clock()>, returning the |
254 | amount of spent processor time in microseconds. | |
37120919 | 255 | |
41cd218c | 256 | =item C<close> |
37120919 | 257 | |
cb1a09d0 AD |
258 | Close the file. This uses file descriptors such as those obtained by calling |
259 | C<POSIX::open>. | |
260 | ||
261 | $fd = POSIX::open( "foo", &POSIX::O_RDONLY ); | |
262 | POSIX::close( $fd ); | |
37120919 AD |
263 | |
264 | Returns C<undef> on failure. | |
265 | ||
4755096e GS |
266 | See also L<perlfunc/close>. |
267 | ||
41cd218c | 268 | =item C<closedir> |
37120919 | 269 | |
4755096e GS |
270 | This is identical to Perl's builtin C<closedir()> function for closing |
271 | a directory handle, see L<perlfunc/closedir>. | |
37120919 | 272 | |
41cd218c | 273 | =item C<cos> |
37120919 | 274 | |
4755096e GS |
275 | This is identical to Perl's builtin C<cos()> function, for returning |
276 | the cosine of its numerical argument, see L<perlfunc/cos>. | |
c2e66d9e | 277 | See also L<Math::Trig>. |
37120919 | 278 | |
41cd218c | 279 | =item C<cosh> |
37120919 | 280 | |
4755096e | 281 | This is identical to the C function C<cosh()>, for returning |
c2e66d9e | 282 | the hyperbolic cosine of its numeric argument. See also L<Math::Trig>. |
37120919 | 283 | |
9d233e12 JH |
284 | =item C<copysign> |
285 | ||
4d0de388 KW |
286 | Returns C<x> but with the sign of C<y> [C99]. |
287 | ||
288 | $x_with_sign_of_y = POSIX::copysign($x, $y); | |
9d233e12 JH |
289 | |
290 | See also L</signbit>. | |
291 | ||
41cd218c | 292 | =item C<creat> |
37120919 | 293 | |
cb1a09d0 AD |
294 | Create a new file. This returns a file descriptor like the ones returned by |
295 | C<POSIX::open>. Use C<POSIX::close> to close the file. | |
296 | ||
297 | $fd = POSIX::creat( "foo", 0611 ); | |
298 | POSIX::close( $fd ); | |
37120919 | 299 | |
4755096e GS |
300 | See also L<perlfunc/sysopen> and its C<O_CREAT> flag. |
301 | ||
41cd218c | 302 | =item C<ctermid> |
37120919 | 303 | |
cb1a09d0 | 304 | Generates the path name for the controlling terminal. |
37120919 AD |
305 | |
306 | $path = POSIX::ctermid(); | |
307 | ||
41cd218c | 308 | =item C<ctime> |
37120919 | 309 | |
4755096e GS |
310 | This is identical to the C function C<ctime()> and equivalent |
311 | to C<asctime(localtime(...))>, see L</asctime> and L</localtime>. | |
37120919 | 312 | |
631637d8 | 313 | =item C<cuserid> [POSIX.1-1988] |
37120919 | 314 | |
4755096e | 315 | Get the login name of the owner of the current process. |
37120919 AD |
316 | |
317 | $name = POSIX::cuserid(); | |
318 | ||
631637d8 MB |
319 | Note: this function has not been specified by POSIX since 1990 and is included |
320 | only for backwards compatibility. New code should use L<C<getlogin()>|perlfunc/getlogin> instead. | |
321 | ||
41cd218c | 322 | =item C<difftime> |
37120919 | 323 | |
4755096e GS |
324 | This is identical to the C function C<difftime()>, for returning |
325 | the time difference (in seconds) between two times (as returned | |
326 | by C<time()>), see L</time>. | |
37120919 | 327 | |
41cd218c | 328 | =item C<div> |
37120919 | 329 | |
4d0de388 | 330 | Not implemented. C<div()> is C-specific, use L<perlfunc/int> on the usual C</> division and |
4755096e | 331 | the modulus C<%>. |
37120919 | 332 | |
41cd218c | 333 | =item C<dup> |
37120919 | 334 | |
4755096e GS |
335 | This is similar to the C function C<dup()>, for duplicating a file |
336 | descriptor. | |
cb1a09d0 AD |
337 | |
338 | This uses file descriptors such as those obtained by calling | |
339 | C<POSIX::open>. | |
37120919 AD |
340 | |
341 | Returns C<undef> on failure. | |
342 | ||
41cd218c | 343 | =item C<dup2> |
37120919 | 344 | |
4755096e GS |
345 | This is similar to the C function C<dup2()>, for duplicating a file |
346 | descriptor to an another known file descriptor. | |
cb1a09d0 AD |
347 | |
348 | This uses file descriptors such as those obtained by calling | |
349 | C<POSIX::open>. | |
37120919 AD |
350 | |
351 | Returns C<undef> on failure. | |
352 | ||
9d233e12 JH |
353 | =item C<erf> |
354 | ||
355 | The error function [C99]. | |
356 | ||
357 | =item C<erfc> | |
358 | ||
359 | The complementary error function [C99]. | |
360 | ||
41cd218c | 361 | =item C<errno> |
37120919 AD |
362 | |
363 | Returns the value of errno. | |
364 | ||
365 | $errno = POSIX::errno(); | |
366 | ||
4755096e GS |
367 | This identical to the numerical values of the C<$!>, see L<perlvar/$ERRNO>. |
368 | ||
41cd218c | 369 | =item C<execl> |
37120919 | 370 | |
4d0de388 | 371 | Not implemented. C<execl()> is C-specific, see L<perlfunc/exec>. |
37120919 | 372 | |
41cd218c | 373 | =item C<execle> |
37120919 | 374 | |
4d0de388 | 375 | Not implemented. C<execle()> is C-specific, see L<perlfunc/exec>. |
37120919 | 376 | |
41cd218c | 377 | =item C<execlp> |
37120919 | 378 | |
4d0de388 | 379 | Not implemented. C<execlp()> is C-specific, see L<perlfunc/exec>. |
37120919 | 380 | |
41cd218c | 381 | =item C<execv> |
37120919 | 382 | |
4d0de388 | 383 | Not implemented. C<execv()> is C-specific, see L<perlfunc/exec>. |
37120919 | 384 | |
41cd218c | 385 | =item C<execve> |
37120919 | 386 | |
4d0de388 | 387 | Not implemented. C<execve()> is C-specific, see L<perlfunc/exec>. |
37120919 | 388 | |
41cd218c | 389 | =item C<execvp> |
37120919 | 390 | |
4d0de388 | 391 | Not implemented. C<execvp()> is C-specific, see L<perlfunc/exec>. |
37120919 | 392 | |
41cd218c | 393 | =item C<exit> |
37120919 | 394 | |
4755096e GS |
395 | This is identical to Perl's builtin C<exit()> function for exiting the |
396 | program, see L<perlfunc/exit>. | |
37120919 | 397 | |
41cd218c | 398 | =item C<exp> |
37120919 | 399 | |
4755096e GS |
400 | This is identical to Perl's builtin C<exp()> function for |
401 | returning the exponent (I<e>-based) of the numerical argument, | |
402 | see L<perlfunc/exp>. | |
37120919 | 403 | |
9d233e12 JH |
404 | =item C<expm1> |
405 | ||
406 | Equivalent to C<exp(x) - 1>, but more precise for small argument values [C99]. | |
407 | ||
408 | See also L</log1p>. | |
409 | ||
41cd218c | 410 | =item C<fabs> |
37120919 | 411 | |
4755096e GS |
412 | This is identical to Perl's builtin C<abs()> function for returning |
413 | the absolute value of the numerical argument, see L<perlfunc/abs>. | |
37120919 | 414 | |
41cd218c | 415 | =item C<fclose> |
37120919 | 416 | |
4d0de388 | 417 | Not implemented. Use method C<IO::Handle::close()> instead, or see L<perlfunc/close>. |
37120919 | 418 | |
41cd218c | 419 | =item C<fcntl> |
37120919 | 420 | |
4755096e GS |
421 | This is identical to Perl's builtin C<fcntl()> function, |
422 | see L<perlfunc/fcntl>. | |
37120919 | 423 | |
41cd218c | 424 | =item C<fdopen> |
37120919 | 425 | |
4d0de388 | 426 | Not implemented. Use method C<IO::Handle::new_from_fd()> instead, or see L<perlfunc/open>. |
37120919 | 427 | |
41cd218c | 428 | =item C<feof> |
37120919 | 429 | |
4d0de388 | 430 | Not implemented. Use method C<IO::Handle::eof()> instead, or see L<perlfunc/eof>. |
37120919 | 431 | |
41cd218c | 432 | =item C<ferror> |
37120919 | 433 | |
4d0de388 | 434 | Not implemented. Use method C<IO::Handle::error()> instead. |
37120919 | 435 | |
41cd218c | 436 | =item C<fflush> |
37120919 | 437 | |
4d0de388 | 438 | Not implemented. Use method C<IO::Handle::flush()> instead. |
41cd218c | 439 | See also C<L<perlvar/$OUTPUT_AUTOFLUSH>>. |
37120919 | 440 | |
41cd218c | 441 | =item C<fgetc> |
37120919 | 442 | |
4d0de388 | 443 | Not implemented. Use method C<IO::Handle::getc()> instead, or see L<perlfunc/read>. |
37120919 | 444 | |
41cd218c | 445 | =item C<fgetpos> |
37120919 | 446 | |
4d0de388 | 447 | Not implemented. Use method C<IO::Seekable::getpos()> instead, or see L<perlfunc/seek>. |
37120919 | 448 | |
41cd218c | 449 | =item C<fgets> |
37120919 | 450 | |
4d0de388 | 451 | Not implemented. Use method C<IO::Handle::gets()> instead. Similar to E<lt>E<gt>, also known |
4755096e | 452 | as L<perlfunc/readline>. |
37120919 | 453 | |
41cd218c | 454 | =item C<fileno> |
37120919 | 455 | |
4d0de388 | 456 | Not implemented. Use method C<IO::Handle::fileno()> instead, or see L<perlfunc/fileno>. |
37120919 | 457 | |
41cd218c | 458 | =item C<floor> |
37120919 | 459 | |
4755096e GS |
460 | This is identical to the C function C<floor()>, returning the largest |
461 | integer value less than or equal to the numerical argument. | |
37120919 | 462 | |
9d233e12 JH |
463 | =item C<fdim> |
464 | ||
4d0de388 | 465 | "Positive difference", S<C<x - y>> if S<C<x E<gt> y>>, zero otherwise [C99]. |
9d233e12 JH |
466 | |
467 | =item C<fegetround> | |
468 | ||
469 | Returns the current floating point rounding mode, one of | |
470 | ||
387e2cd4 | 471 | FE_TONEAREST FE_TOWARDZERO FE_UPWARD FE_DOWNWARD |
9d233e12 | 472 | |
4d0de388 | 473 | C<FE_TONEAREST> is like L</round>, C<FE_TOWARDZERO> is like L</trunc> [C99]. |
9d233e12 JH |
474 | |
475 | =item C<fesetround> | |
476 | ||
d7a0f0b0 | 477 | Sets the floating point rounding mode, see L</fegetround> [C99]. |
9d233e12 JH |
478 | |
479 | =item C<fma> | |
480 | ||
4d0de388 | 481 | "Fused multiply-add", S<C<x * y + z>>, possibly faster (and less lossy) |
9d233e12 JH |
482 | than the explicit two operations [C99]. |
483 | ||
4d0de388 KW |
484 | my $fused = POSIX::fma($x, $y, $z); |
485 | ||
9d233e12 JH |
486 | =item C<fmax> |
487 | ||
4d0de388 KW |
488 | Maximum of C<x> and C<y>, except when either is C<NaN>, returns the other [C99]. |
489 | ||
490 | my $min = POSIX::fmax($x, $y); | |
9d233e12 JH |
491 | |
492 | =item C<fmin> | |
493 | ||
4d0de388 KW |
494 | Minimum of C<x> and C<y>, except when either is C<NaN>, returns the other [C99]. |
495 | ||
496 | my $min = POSIX::fmin($x, $y); | |
9d233e12 | 497 | |
41cd218c | 498 | =item C<fmod> |
37120919 AD |
499 | |
500 | This is identical to the C function C<fmod()>. | |
501 | ||
847f7ebc | 502 | $r = fmod($x, $y); |
4755096e | 503 | |
4d0de388 | 504 | It returns the remainder S<C<$r = $x - $n*$y>>, where S<C<$n = trunc($x/$y)>>. |
4755096e GS |
505 | The C<$r> has the same sign as C<$x> and magnitude (absolute value) |
506 | less than the magnitude of C<$y>. | |
507 | ||
41cd218c | 508 | =item C<fopen> |
37120919 | 509 | |
4d0de388 | 510 | Not implemented. Use method C<IO::File::open()> instead, or see L<perlfunc/open>. |
37120919 | 511 | |
41cd218c | 512 | =item C<fork> |
37120919 | 513 | |
c2e66d9e GS |
514 | This is identical to Perl's builtin C<fork()> function |
515 | for duplicating the current process, see L<perlfunc/fork> | |
516 | and L<perlfork> if you are in Windows. | |
37120919 | 517 | |
41cd218c | 518 | =item C<fpathconf> |
37120919 | 519 | |
cb1a09d0 AD |
520 | Retrieves the value of a configurable limit on a file or directory. This |
521 | uses file descriptors such as those obtained by calling C<POSIX::open>. | |
522 | ||
523 | The following will determine the maximum length of the longest allowable | |
f703fc96 | 524 | pathname on the filesystem which holds F</var/foo>. |
cb1a09d0 | 525 | |
2359510d | 526 | $fd = POSIX::open( "/var/foo", &POSIX::O_RDONLY ); |
b70c169c | 527 | $path_max = POSIX::fpathconf($fd, &POSIX::_PC_PATH_MAX); |
37120919 AD |
528 | |
529 | Returns C<undef> on failure. | |
530 | ||
9d233e12 JH |
531 | =item C<fpclassify> |
532 | ||
533 | Returns one of | |
534 | ||
535 | FP_NORMAL FP_ZERO FP_SUBNORMAL FP_INFINITE FP_NAN | |
536 | ||
d7a0f0b0 JH |
537 | telling the class of the argument [C99]. C<FP_INFINITE> is positive |
538 | or negative infinity, C<FP_NAN> is not-a-number. C<FP_SUBNORMAL> | |
539 | means subnormal numbers (also known as denormals), very small numbers | |
540 | with low precision. C<FP_ZERO> is zero. C<FP_NORMAL> is all the rest. | |
9d233e12 | 541 | |
41cd218c | 542 | =item C<fprintf> |
37120919 | 543 | |
4d0de388 | 544 | Not implemented. C<fprintf()> is C-specific, see L<perlfunc/printf> instead. |
37120919 | 545 | |
41cd218c | 546 | =item C<fputc> |
37120919 | 547 | |
4d0de388 | 548 | Not implemented. C<fputc()> is C-specific, see L<perlfunc/print> instead. |
37120919 | 549 | |
41cd218c | 550 | =item C<fputs> |
37120919 | 551 | |
4d0de388 | 552 | Not implemented. C<fputs()> is C-specific, see L<perlfunc/print> instead. |
37120919 | 553 | |
41cd218c | 554 | =item C<fread> |
37120919 | 555 | |
4d0de388 | 556 | Not implemented. C<fread()> is C-specific, see L<perlfunc/read> instead. |
37120919 | 557 | |
41cd218c | 558 | =item C<free> |
37120919 | 559 | |
4d0de388 | 560 | Not implemented. C<free()> is C-specific. Perl does memory management transparently. |
37120919 | 561 | |
41cd218c | 562 | =item C<freopen> |
37120919 | 563 | |
4d0de388 | 564 | Not implemented. C<freopen()> is C-specific, see L<perlfunc/open> instead. |
37120919 | 565 | |
41cd218c | 566 | =item C<frexp> |
37120919 | 567 | |
cb1a09d0 AD |
568 | Return the mantissa and exponent of a floating-point number. |
569 | ||
4755096e | 570 | ($mantissa, $exponent) = POSIX::frexp( 1.234e56 ); |
37120919 | 571 | |
41cd218c | 572 | =item C<fscanf> |
37120919 | 573 | |
4d0de388 | 574 | Not implemented. C<fscanf()> is C-specific, use E<lt>E<gt> and regular expressions instead. |
37120919 | 575 | |
41cd218c | 576 | =item C<fseek> |
37120919 | 577 | |
4d0de388 | 578 | Not implemented. Use method C<IO::Seekable::seek()> instead, or see L<perlfunc/seek>. |
37120919 | 579 | |
41cd218c | 580 | =item C<fsetpos> |
37120919 | 581 | |
4d0de388 | 582 | Not implemented. Use method C<IO::Seekable::setpos()> instead, or seek L<perlfunc/seek>. |
37120919 | 583 | |
41cd218c | 584 | =item C<fstat> |
37120919 | 585 | |
cb1a09d0 AD |
586 | Get file status. This uses file descriptors such as those obtained by |
587 | calling C<POSIX::open>. The data returned is identical to the data from | |
588 | Perl's builtin C<stat> function. | |
589 | ||
590 | $fd = POSIX::open( "foo", &POSIX::O_RDONLY ); | |
591 | @stats = POSIX::fstat( $fd ); | |
37120919 | 592 | |
41cd218c | 593 | =item C<fsync> |
f0709b24 | 594 | |
4d0de388 | 595 | Not implemented. Use method C<IO::Handle::sync()> instead. |
f0709b24 | 596 | |
41cd218c | 597 | =item C<ftell> |
37120919 | 598 | |
4d0de388 | 599 | Not implemented. Use method C<IO::Seekable::tell()> instead, or see L<perlfunc/tell>. |
37120919 | 600 | |
41cd218c | 601 | =item C<fwrite> |
37120919 | 602 | |
4d0de388 | 603 | Not implemented. C<fwrite()> is C-specific, see L<perlfunc/print> instead. |
37120919 | 604 | |
41cd218c | 605 | =item C<getc> |
37120919 | 606 | |
4755096e GS |
607 | This is identical to Perl's builtin C<getc()> function, |
608 | see L<perlfunc/getc>. | |
37120919 | 609 | |
41cd218c | 610 | =item C<getchar> |
37120919 | 611 | |
4755096e GS |
612 | Returns one character from STDIN. Identical to Perl's C<getc()>, |
613 | see L<perlfunc/getc>. | |
37120919 | 614 | |
41cd218c | 615 | =item C<getcwd> |
37120919 AD |
616 | |
617 | Returns the name of the current working directory. | |
4755096e | 618 | See also L<Cwd>. |
37120919 | 619 | |
41cd218c | 620 | =item C<getegid> |
37120919 | 621 | |
4755096e GS |
622 | Returns the effective group identifier. Similar to Perl' s builtin |
623 | variable C<$(>, see L<perlvar/$EGID>. | |
37120919 | 624 | |
41cd218c | 625 | =item C<getenv> |
37120919 | 626 | |
d7f8936a | 627 | Returns the value of the specified environment variable. |
4755096e | 628 | The same information is available through the C<%ENV> array. |
37120919 | 629 | |
41cd218c | 630 | =item C<geteuid> |
37120919 | 631 | |
4755096e GS |
632 | Returns the effective user identifier. Identical to Perl's builtin C<$E<gt>> |
633 | variable, see L<perlvar/$EUID>. | |
37120919 | 634 | |
41cd218c | 635 | =item C<getgid> |
37120919 | 636 | |
4755096e GS |
637 | Returns the user's real group identifier. Similar to Perl's builtin |
638 | variable C<$)>, see L<perlvar/$GID>. | |
37120919 | 639 | |
41cd218c | 640 | =item C<getgrgid> |
37120919 | 641 | |
4755096e GS |
642 | This is identical to Perl's builtin C<getgrgid()> function for |
643 | returning group entries by group identifiers, see | |
644 | L<perlfunc/getgrgid>. | |
37120919 | 645 | |
41cd218c | 646 | =item C<getgrnam> |
37120919 | 647 | |
4755096e GS |
648 | This is identical to Perl's builtin C<getgrnam()> function for |
649 | returning group entries by group names, see L<perlfunc/getgrnam>. | |
37120919 | 650 | |
41cd218c | 651 | =item C<getgroups> |
37120919 | 652 | |
4755096e GS |
653 | Returns the ids of the user's supplementary groups. Similar to Perl's |
654 | builtin variable C<$)>, see L<perlvar/$GID>. | |
37120919 | 655 | |
41cd218c | 656 | =item C<getlogin> |
37120919 | 657 | |
4755096e GS |
658 | This is identical to Perl's builtin C<getlogin()> function for |
659 | returning the user name associated with the current session, see | |
660 | L<perlfunc/getlogin>. | |
37120919 | 661 | |
07bb61ac JH |
662 | =item C<getpayload> |
663 | ||
664 | use POSIX ':nan_payload'; | |
665 | getpayload($var) | |
666 | ||
667 | Returns the C<NaN> payload. | |
668 | ||
669 | Note the API instability warning in L</setpayload>. | |
670 | ||
671 | See L</nan> for more discussion about C<NaN>. | |
672 | ||
41cd218c | 673 | =item C<getpgrp> |
37120919 | 674 | |
4755096e | 675 | This is identical to Perl's builtin C<getpgrp()> function for |
d7f8936a | 676 | returning the process group identifier of the current process, see |
4755096e | 677 | L<perlfunc/getpgrp>. |
37120919 | 678 | |
41cd218c | 679 | =item C<getpid> |
37120919 | 680 | |
4755096e GS |
681 | Returns the process identifier. Identical to Perl's builtin |
682 | variable C<$$>, see L<perlvar/$PID>. | |
37120919 | 683 | |
41cd218c | 684 | =item C<getppid> |
37120919 | 685 | |
4755096e GS |
686 | This is identical to Perl's builtin C<getppid()> function for |
687 | returning the process identifier of the parent process of the current | |
688 | process , see L<perlfunc/getppid>. | |
37120919 | 689 | |
41cd218c | 690 | =item C<getpwnam> |
37120919 | 691 | |
4755096e GS |
692 | This is identical to Perl's builtin C<getpwnam()> function for |
693 | returning user entries by user names, see L<perlfunc/getpwnam>. | |
37120919 | 694 | |
41cd218c | 695 | =item C<getpwuid> |
37120919 | 696 | |
4755096e GS |
697 | This is identical to Perl's builtin C<getpwuid()> function for |
698 | returning user entries by user identifiers, see L<perlfunc/getpwuid>. | |
37120919 | 699 | |
41cd218c | 700 | =item C<gets> |
37120919 | 701 | |
4755096e GS |
702 | Returns one line from C<STDIN>, similar to E<lt>E<gt>, also known |
703 | as the C<readline()> function, see L<perlfunc/readline>. | |
704 | ||
705 | B<NOTE>: if you have C programs that still use C<gets()>, be very | |
706 | afraid. The C<gets()> function is a source of endless grief because | |
707 | it has no buffer overrun checks. It should B<never> be used. The | |
708 | C<fgets()> function should be preferred instead. | |
37120919 | 709 | |
41cd218c | 710 | =item C<getuid> |
37120919 | 711 | |
4755096e GS |
712 | Returns the user's identifier. Identical to Perl's builtin C<$E<lt>> variable, |
713 | see L<perlvar/$UID>. | |
37120919 | 714 | |
41cd218c | 715 | =item C<gmtime> |
37120919 | 716 | |
4755096e GS |
717 | This is identical to Perl's builtin C<gmtime()> function for |
718 | converting seconds since the epoch to a date in Greenwich Mean Time, | |
719 | see L<perlfunc/gmtime>. | |
37120919 | 720 | |
9d233e12 JH |
721 | =item C<hypot> |
722 | ||
4d0de388 | 723 | Equivalent to C<S<sqrt(x * x + y * y)>> except more stable on very large |
9d233e12 JH |
724 | or very small arguments [C99]. |
725 | ||
726 | =item C<ilogb> | |
727 | ||
351ab2ad | 728 | Integer binary logarithm [C99] |
9d233e12 | 729 | |
4d0de388 | 730 | For example C<ilogb(20)> is 4, as an integer. |
351ab2ad JH |
731 | |
732 | See also L</logb>. | |
9d233e12 | 733 | |
d7a0f0b0 JH |
734 | =item C<Inf> |
735 | ||
736 | The infinity as a constant: | |
737 | ||
738 | use POSIX qw(Inf); | |
739 | my $pos_inf = +Inf; # Or just Inf. | |
740 | my $neg_inf = -Inf; | |
741 | ||
742 | See also L</isinf>, and L</fpclassify>. | |
743 | ||
41cd218c | 744 | =item C<isalnum> |
37120919 | 745 | |
47ed9d9e KW |
746 | This function has been removed as of v5.24. It was very similar to |
747 | matching against S<C<qr/ ^ [[:alnum:]]+ $ /x>>, which you should convert | |
748 | to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 749 | |
41cd218c | 750 | =item C<isalpha> |
37120919 | 751 | |
47ed9d9e KW |
752 | This function has been removed as of v5.24. It was very similar to |
753 | matching against S<C<qr/ ^ [[:alpha:]]+ $ /x>>, which you should convert | |
754 | to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 755 | |
41cd218c | 756 | =item C<isatty> |
37120919 AD |
757 | |
758 | Returns a boolean indicating whether the specified filehandle is connected | |
4755096e | 759 | to a tty. Similar to the C<-t> operator, see L<perlfunc/-X>. |
37120919 | 760 | |
41cd218c | 761 | =item C<iscntrl> |
37120919 | 762 | |
47ed9d9e KW |
763 | This function has been removed as of v5.24. It was very similar to |
764 | matching against S<C<qr/ ^ [[:cntrl:]]+ $ /x>>, which you should convert | |
765 | to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 766 | |
41cd218c | 767 | =item C<isdigit> |
37120919 | 768 | |
47ed9d9e KW |
769 | This function has been removed as of v5.24. It was very similar to |
770 | matching against S<C<qr/ ^ [[:digit:]]+ $ /x>>, which you should convert | |
771 | to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 772 | |
9d233e12 JH |
773 | =item C<isfinite> |
774 | ||
775 | Returns true if the argument is a finite number (that is, not an | |
776 | infinity, or the not-a-number) [C99]. | |
777 | ||
3823048b | 778 | See also L</isinf>, L</isnan>, and L</fpclassify>. |
9d233e12 | 779 | |
41cd218c | 780 | =item C<isgraph> |
37120919 | 781 | |
47ed9d9e KW |
782 | This function has been removed as of v5.24. It was very similar to |
783 | matching against S<C<qr/ ^ [[:graph:]]+ $ /x>>, which you should convert | |
784 | to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 785 | |
9d233e12 JH |
786 | =item C<isgreater> |
787 | ||
788 | (Also C<isgreaterequal>, C<isless>, C<islessequal>, C<islessgreater>, | |
789 | C<isunordered>) | |
790 | ||
4d0de388 | 791 | Floating point comparisons which handle the C<NaN> [C99]. |
9d233e12 JH |
792 | |
793 | =item C<isinf> | |
794 | ||
795 | Returns true if the argument is an infinity (positive or negative) [C99]. | |
796 | ||
d7a0f0b0 | 797 | See also L</Inf>, L</isnan>, L</isfinite>, and L</fpclassify>. |
9d233e12 | 798 | |
41cd218c | 799 | =item C<islower> |
37120919 | 800 | |
47ed9d9e KW |
801 | This function has been removed as of v5.24. It was very similar to |
802 | matching against S<C<qr/ ^ [[:lower:]]+ $ /x>>, which you should convert | |
803 | to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 804 | |
9d233e12 JH |
805 | =item C<isnan> |
806 | ||
4d0de388 | 807 | Returns true if the argument is C<NaN> (not-a-number) [C99]. |
9d233e12 | 808 | |
4d0de388 | 809 | Note that you cannot test for "C<NaN>-ness" with |
9d233e12 JH |
810 | |
811 | $x == $x | |
812 | ||
4d0de388 | 813 | since the C<NaN> is not equivalent to anything, B<including itself>. |
9d233e12 | 814 | |
d7a0f0b0 | 815 | See also L</nan>, L</NaN>, L</isinf>, and L</fpclassify>. |
9d233e12 JH |
816 | |
817 | =item C<isnormal> | |
818 | ||
819 | Returns true if the argument is normal (that is, not a subnormal/denormal, | |
820 | and not an infinity, or a not-a-number) [C99]. | |
821 | ||
822 | See also L</isfinite>, and L</fpclassify>. | |
823 | ||
41cd218c | 824 | =item C<isprint> |
37120919 | 825 | |
47ed9d9e KW |
826 | This function has been removed as of v5.24. It was very similar to |
827 | matching against S<C<qr/ ^ [[:print:]]+ $ /x>>, which you should convert | |
828 | to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 829 | |
41cd218c | 830 | =item C<ispunct> |
37120919 | 831 | |
47ed9d9e KW |
832 | This function has been removed as of v5.24. It was very similar to |
833 | matching against S<C<qr/ ^ [[:punct:]]+ $ /x>>, which you should convert | |
834 | to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 835 | |
07bb61ac JH |
836 | =item C<issignaling> |
837 | ||
838 | use POSIX ':nan_payload'; | |
839 | issignaling($var, $payload) | |
840 | ||
841 | Return true if the argument is a I<signaling> NaN. | |
842 | ||
843 | Note the API instability warning in L</setpayload>. | |
844 | ||
845 | See L</nan> for more discussion about C<NaN>. | |
846 | ||
41cd218c | 847 | =item C<isspace> |
37120919 | 848 | |
47ed9d9e KW |
849 | This function has been removed as of v5.24. It was very similar to |
850 | matching against S<C<qr/ ^ [[:space:]]+ $ /x>>, which you should convert | |
851 | to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 852 | |
41cd218c | 853 | =item C<isupper> |
37120919 | 854 | |
47ed9d9e KW |
855 | This function has been removed as of v5.24. It was very similar to |
856 | matching against S<C<qr/ ^ [[:upper:]]+ $ /x>>, which you should convert | |
857 | to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 858 | |
41cd218c | 859 | =item C<isxdigit> |
37120919 | 860 | |
47ed9d9e KW |
861 | This function has been removed as of v5.24. It was very similar to |
862 | matching against S<C<qr/ ^ [[:xdigit:]]+ $ /x>>, which you should | |
863 | convert to use instead. See L<perlrecharclass/POSIX Character Classes>. | |
37120919 | 864 | |
9d233e12 JH |
865 | =item C<j0> |
866 | ||
98ab3abf AP |
867 | =item C<j1> |
868 | ||
869 | =item C<jn> | |
870 | ||
871 | =item C<y0> | |
872 | ||
873 | =item C<y1> | |
874 | ||
875 | =item C<yn> | |
9d233e12 JH |
876 | |
877 | The Bessel function of the first kind of the order zero. | |
878 | ||
41cd218c | 879 | =item C<kill> |
37120919 | 880 | |
4755096e | 881 | This is identical to Perl's builtin C<kill()> function for sending |
c2e66d9e | 882 | signals to processes (often to terminate them), see L<perlfunc/kill>. |
37120919 | 883 | |
41cd218c | 884 | =item C<labs> |
37120919 | 885 | |
4d0de388 | 886 | Not implemented. (For returning absolute values of long integers.) |
41cd218c | 887 | C<labs()> is C-specific, see L<perlfunc/abs> instead. |
37120919 | 888 | |
41cd218c | 889 | =item C<lchown> |
c5eef087 DFC |
890 | |
891 | This is identical to the C function, except the order of arguments is | |
892 | consistent with Perl's builtin C<chown()> with the added restriction | |
4d0de388 KW |
893 | of only one path, not a list of paths. Does the same thing as the |
894 | C<chown()> function but changes the owner of a symbolic link instead | |
c5eef087 DFC |
895 | of the file the symbolic link points to. |
896 | ||
4d0de388 KW |
897 | POSIX::lchown($uid, $gid, $file_path); |
898 | ||
41cd218c | 899 | =item C<ldexp> |
37120919 | 900 | |
4755096e GS |
901 | This is identical to the C function C<ldexp()> |
902 | for multiplying floating point numbers with powers of two. | |
903 | ||
904 | $x_quadrupled = POSIX::ldexp($x, 2); | |
37120919 | 905 | |
41cd218c | 906 | =item C<ldiv> |
37120919 | 907 | |
4d0de388 | 908 | Not implemented. (For computing dividends of long integers.) |
41cd218c | 909 | C<ldiv()> is C-specific, use C</> and C<int()> instead. |
37120919 | 910 | |
9d233e12 JH |
911 | =item C<lgamma> |
912 | ||
913 | The logarithm of the Gamma function [C99]. | |
914 | ||
915 | See also L</tgamma>. | |
916 | ||
917 | =item C<log1p> | |
918 | ||
4d0de388 | 919 | Equivalent to S<C<log(1 + x)>>, but more stable results for small argument |
9d233e12 JH |
920 | values [C99]. |
921 | ||
922 | =item C<log2> | |
923 | ||
924 | Logarithm base two [C99]. | |
925 | ||
926 | See also L</expm1>. | |
927 | ||
928 | =item C<logb> | |
929 | ||
930 | Integer binary logarithm [C99]. | |
931 | ||
4d0de388 | 932 | For example C<logb(20)> is 4, as a floating point number. |
351ab2ad JH |
933 | |
934 | See also L</ilogb>. | |
9d233e12 | 935 | |
41cd218c | 936 | =item C<link> |
37120919 | 937 | |
4755096e GS |
938 | This is identical to Perl's builtin C<link()> function |
939 | for creating hard links into files, see L<perlfunc/link>. | |
37120919 | 940 | |
41cd218c | 941 | =item C<localeconv> |
37120919 | 942 | |
cb1a09d0 | 943 | Get numeric formatting information. Returns a reference to a hash |
a835cd47 | 944 | containing the current underlying locale's formatting values. Users of this function |
dfcc8045 KW |
945 | should also read L<perllocale>, which provides a comprehensive |
946 | discussion of Perl locale handling, including | |
947 | L<a section devoted to this function|perllocale/The localeconv function>. | |
e9bc6d6b | 948 | Prior to Perl 5.28, or when operating in a non thread-safe environment, |
8b24ca2d | 949 | it should not be used in a threaded application unless it's certain that |
aa2bc4d3 KW |
950 | the underlying locale is C or POSIX. This is because it otherwise |
951 | changes the locale, which globally affects all threads simultaneously. | |
69c5e0db KW |
952 | Windows platforms starting with Visual Studio 2005 are mostly |
953 | thread-safe, but use of this function in those prior to Visual Studio | |
954 | 2015 can interefere with a thread that has called | |
955 | L<perlapi/switch_to_global_locale>. | |
cb1a09d0 | 956 | |
4755096e | 957 | Here is how to query the database for the B<de> (Deutsch or German) locale. |
cb1a09d0 | 958 | |
c4e34987 DP |
959 | my $loc = POSIX::setlocale( &POSIX::LC_ALL, "de" ); |
960 | print "Locale: \"$loc\"\n"; | |
961 | my $lconv = POSIX::localeconv(); | |
962 | foreach my $property (qw( | |
963 | decimal_point | |
964 | thousands_sep | |
965 | grouping | |
966 | int_curr_symbol | |
967 | currency_symbol | |
968 | mon_decimal_point | |
969 | mon_thousands_sep | |
970 | mon_grouping | |
971 | positive_sign | |
972 | negative_sign | |
973 | int_frac_digits | |
974 | frac_digits | |
975 | p_cs_precedes | |
976 | p_sep_by_space | |
977 | n_cs_precedes | |
978 | n_sep_by_space | |
979 | p_sign_posn | |
980 | n_sign_posn | |
b15c1b56 AF |
981 | int_p_cs_precedes |
982 | int_p_sep_by_space | |
983 | int_n_cs_precedes | |
984 | int_n_sep_by_space | |
985 | int_p_sign_posn | |
986 | int_n_sign_posn | |
c4e34987 DP |
987 | )) |
988 | { | |
b70c169c FC |
989 | printf qq(%s: "%s",\n), |
990 | $property, $lconv->{$property}; | |
c4e34987 | 991 | } |
37120919 | 992 | |
4d0de388 KW |
993 | The members whose names begin with C<int_p_> and C<int_n_> were added by |
994 | POSIX.1-2008 and are only available on systems that support them. | |
b15c1b56 | 995 | |
41cd218c | 996 | =item C<localtime> |
37120919 | 997 | |
4755096e | 998 | This is identical to Perl's builtin C<localtime()> function for |
dc416353 JK |
999 | converting seconds since the epoch to a date see L<perlfunc/localtime> except |
1000 | that C<POSIX::localtime()> must be provided an explicit value (rather than | |
bda53d3e | 1001 | relying on an implicit C<$_>): |
dc416353 | 1002 | |
bda53d3e | 1003 | @localtime = POSIX::localtime(time); # good |
dc416353 | 1004 | |
bda53d3e | 1005 | @localtime = localtime(); # good |
dc416353 | 1006 | |
bda53d3e | 1007 | @localtime = POSIX::localtime(); # throws exception |
37120919 | 1008 | |
41cd218c | 1009 | =item C<log> |
37120919 | 1010 | |
4755096e GS |
1011 | This is identical to Perl's builtin C<log()> function, |
1012 | returning the natural (I<e>-based) logarithm of the numerical argument, | |
1013 | see L<perlfunc/log>. | |
37120919 | 1014 | |
41cd218c | 1015 | =item C<log10> |
37120919 | 1016 | |
4755096e GS |
1017 | This is identical to the C function C<log10()>, |
1018 | returning the 10-base logarithm of the numerical argument. | |
1019 | You can also use | |
1020 | ||
1021 | sub log10 { log($_[0]) / log(10) } | |
1022 | ||
1023 | or | |
1024 | ||
3609ea0d | 1025 | sub log10 { log($_[0]) / 2.30258509299405 } |
4755096e GS |
1026 | |
1027 | or | |
1028 | ||
1029 | sub log10 { log($_[0]) * 0.434294481903252 } | |
37120919 | 1030 | |
41cd218c | 1031 | =item C<longjmp> |
37120919 | 1032 | |
4d0de388 | 1033 | Not implemented. C<longjmp()> is C-specific: use L<perlfunc/die> instead. |
37120919 | 1034 | |
41cd218c | 1035 | =item C<lseek> |
37120919 | 1036 | |
8903cb82 | 1037 | Move the file's read/write position. This uses file descriptors such as |
cb1a09d0 AD |
1038 | those obtained by calling C<POSIX::open>. |
1039 | ||
1040 | $fd = POSIX::open( "foo", &POSIX::O_RDONLY ); | |
1041 | $off_t = POSIX::lseek( $fd, 0, &POSIX::SEEK_SET ); | |
37120919 AD |
1042 | |
1043 | Returns C<undef> on failure. | |
1044 | ||
9d233e12 JH |
1045 | =item C<lrint> |
1046 | ||
351ab2ad JH |
1047 | Depending on the current floating point rounding mode, rounds the |
1048 | argument either toward nearest (like L</round>), toward zero (like | |
1049 | L</trunc>), downward (toward negative infinity), or upward (toward | |
1050 | positive infinity) [C99]. | |
9d233e12 | 1051 | |
351ab2ad | 1052 | For the rounding mode, see L</fegetround>. |
9d233e12 | 1053 | |
9e010b89 JH |
1054 | =item C<lround> |
1055 | ||
1056 | Like L</round>, but as integer, as opposed to floating point [C99]. | |
1057 | ||
1058 | See also L</ceil>, L</floor>, L</trunc>. | |
1059 | ||
25a9f0e7 AC |
1060 | Owing to an oversight, this is not currently exported by default, or as part of |
1061 | the C<:math_h_c99> export tag; importing it must therefore be done by explicit | |
abc9e18b | 1062 | name. |
25a9f0e7 | 1063 | |
41cd218c | 1064 | =item C<malloc> |
37120919 | 1065 | |
4d0de388 | 1066 | Not implemented. C<malloc()> is C-specific. Perl does memory management transparently. |
37120919 | 1067 | |
41cd218c | 1068 | =item C<mblen> |
37120919 | 1069 | |
cb1a09d0 | 1070 | This is identical to the C function C<mblen()>. |
351ab2ad JH |
1071 | |
1072 | Core Perl does not have any support for the wide and multibyte | |
4d0de388 KW |
1073 | characters of the C standards, except under UTF-8 locales, so this might |
1074 | be a rather useless function. | |
351ab2ad JH |
1075 | |
1076 | However, Perl supports Unicode, see L<perluniintro>. | |
37120919 | 1077 | |
41cd218c | 1078 | =item C<mbstowcs> |
37120919 | 1079 | |
cb1a09d0 | 1080 | This is identical to the C function C<mbstowcs()>. |
351ab2ad JH |
1081 | |
1082 | See L</mblen>. | |
37120919 | 1083 | |
41cd218c | 1084 | =item C<mbtowc> |
37120919 | 1085 | |
cb1a09d0 | 1086 | This is identical to the C function C<mbtowc()>. |
351ab2ad JH |
1087 | |
1088 | See L</mblen>. | |
37120919 | 1089 | |
41cd218c | 1090 | =item C<memchr> |
37120919 | 1091 | |
4d0de388 | 1092 | Not implemented. C<memchr()> is C-specific, see L<perlfunc/index> instead. |
37120919 | 1093 | |
41cd218c | 1094 | =item C<memcmp> |
37120919 | 1095 | |
4d0de388 | 1096 | Not implemented. C<memcmp()> is C-specific, use C<eq> instead, see L<perlop>. |
37120919 | 1097 | |
41cd218c | 1098 | =item C<memcpy> |
37120919 | 1099 | |
4d0de388 | 1100 | Not implemented. C<memcpy()> is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>. |
37120919 | 1101 | |
41cd218c | 1102 | =item C<memmove> |
37120919 | 1103 | |
4d0de388 | 1104 | Not implemented. C<memmove()> is C-specific, use C<=>, see L<perlop>, or see L<perlfunc/substr>. |
37120919 | 1105 | |
41cd218c | 1106 | =item C<memset> |
37120919 | 1107 | |
4d0de388 | 1108 | Not implemented. C<memset()> is C-specific, use C<x> instead, see L<perlop>. |
37120919 | 1109 | |
41cd218c | 1110 | =item C<mkdir> |
37120919 | 1111 | |
4755096e GS |
1112 | This is identical to Perl's builtin C<mkdir()> function |
1113 | for creating directories, see L<perlfunc/mkdir>. | |
37120919 | 1114 | |
41cd218c | 1115 | =item C<mkfifo> |
37120919 | 1116 | |
4755096e GS |
1117 | This is similar to the C function C<mkfifo()> for creating |
1118 | FIFO special files. | |
37120919 | 1119 | |
4755096e GS |
1120 | if (mkfifo($path, $mode)) { .... |
1121 | ||
1122 | Returns C<undef> on failure. The C<$mode> is similar to the | |
220f811a JH |
1123 | mode of C<mkdir()>, see L<perlfunc/mkdir>, though for C<mkfifo> |
1124 | you B<must> specify the C<$mode>. | |
37120919 | 1125 | |
41cd218c | 1126 | =item C<mktime> |
37120919 | 1127 | |
cb1a09d0 AD |
1128 | Convert date/time info to a calendar time. |
1129 | ||
1130 | Synopsis: | |
1131 | ||
b70c169c FC |
1132 | mktime(sec, min, hour, mday, mon, year, wday = 0, |
1133 | yday = 0, isdst = -1) | |
cb1a09d0 | 1134 | |
4d0de388 KW |
1135 | The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero, |
1136 | I<i.e.>, January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The | |
1137 | year (C<year>) is given in years since 1900; I<i.e.>, the year 1995 is 95; the | |
cb1a09d0 AD |
1138 | year 2001 is 101. Consult your system's C<mktime()> manpage for details |
1139 | about these and the other arguments. | |
1140 | ||
1141 | Calendar time for December 12, 1995, at 10:30 am. | |
1142 | ||
1143 | $time_t = POSIX::mktime( 0, 30, 10, 12, 11, 95 ); | |
1144 | print "Date = ", POSIX::ctime($time_t); | |
37120919 AD |
1145 | |
1146 | Returns C<undef> on failure. | |
1147 | ||
41cd218c | 1148 | =item C<modf> |
37120919 | 1149 | |
cb1a09d0 AD |
1150 | Return the integral and fractional parts of a floating-point number. |
1151 | ||
1152 | ($fractional, $integral) = POSIX::modf( 3.14 ); | |
37120919 | 1153 | |
351ab2ad JH |
1154 | See also L</round>. |
1155 | ||
d7a0f0b0 JH |
1156 | =item C<NaN> |
1157 | ||
1158 | The not-a-number as a constant: | |
1159 | ||
1160 | use POSIX qw(NaN); | |
1161 | my $nan = NaN; | |
1162 | ||
1163 | See also L</nan>, C</isnan>, and L</fpclassify>. | |
1164 | ||
9d233e12 JH |
1165 | =item C<nan> |
1166 | ||
07bb61ac JH |
1167 | my $nan = nan(); |
1168 | ||
1169 | Returns C<NaN>, not-a-number [C99]. | |
1170 | ||
1171 | The returned NaN is always a I<quiet> NaN, as opposed to I<signaling>. | |
1172 | ||
1173 | With an argument, can be used to generate a NaN with I<payload>. | |
1174 | The argument is first interpreted as a floating point number, | |
1175 | but then any fractional parts are truncated (towards zero), | |
1176 | and the value is interpreted as an unsigned integer. | |
1177 | The bits of this integer are stored in the unused bits of the NaN. | |
1178 | ||
1179 | The result has a dual nature: it is a NaN, but it also carries | |
1180 | the integer inside it. The integer can be retrieved with L</getpayload>. | |
1181 | Note, though, that the payload is not propagated, not even on copies, | |
1182 | and definitely not in arithmetic operations. | |
1183 | ||
1184 | How many bits fit in the NaN depends on what kind of floating points | |
1185 | are being used, but on the most common platforms (64-bit IEEE 754, | |
1186 | or the x86 80-bit long doubles) there are 51 and 61 bits available, | |
1187 | respectively. (There would be 52 and 62, but the quiet/signaling | |
1188 | bit of NaNs takes away one.) However, because of the floating-point-to- | |
1189 | integer-and-back conversions, please test carefully whether you get back | |
1190 | what you put in. If your integers are only 32 bits wide, you probably | |
1191 | should not rely on more than 32 bits of payload. | |
9d233e12 | 1192 | |
07bb61ac JH |
1193 | Whether a "signaling" NaN is in any way different from a "quiet" NaN, |
1194 | depends on the platform. Also note that the payload of the default | |
1195 | NaN (no argument to nan()) is not necessarily zero, use C<setpayload> | |
8384a6d6 JH |
1196 | to explicitly set the payload. On some platforms like the 32-bit x86, |
1197 | (unless using the 80-bit long doubles) the signaling bit is not supported | |
1198 | at all. | |
07bb61ac | 1199 | |
d7a0f0b0 | 1200 | See also L</isnan>, L</NaN>, L</setpayload> and L</issignaling>. |
351ab2ad | 1201 | |
9d233e12 JH |
1202 | =item C<nearbyint> |
1203 | ||
1204 | Returns the nearest integer to the argument, according to the current | |
1205 | rounding mode (see L</fegetround>) [C99]. | |
1206 | ||
1207 | =item C<nextafter> | |
1208 | ||
4d0de388 KW |
1209 | Returns the next representable floating point number after C<x> in the |
1210 | direction of C<y> [C99]. | |
1211 | ||
1212 | my $nextafter = POSIX::nextafter($x, $y); | |
9d233e12 JH |
1213 | |
1214 | Like L</nexttoward>, but potentially less accurate. | |
1215 | ||
1216 | =item C<nexttoward> | |
1217 | ||
4d0de388 KW |
1218 | Returns the next representable floating point number after C<x> in the |
1219 | direction of C<y> [C99]. | |
1220 | ||
1221 | my $nexttoward = POSIX::nexttoward($x, $y); | |
9d233e12 JH |
1222 | |
1223 | Like L</nextafter>, but potentially more accurate. | |
1224 | ||
41cd218c | 1225 | =item C<nice> |
37120919 | 1226 | |
4755096e GS |
1227 | This is similar to the C function C<nice()>, for changing |
1228 | the scheduling preference of the current process. Positive | |
4d0de388 KW |
1229 | arguments mean a more polite process, negative values a more |
1230 | needy process. Normal (non-root) user processes can only change towards | |
1231 | being more polite. | |
37120919 AD |
1232 | |
1233 | Returns C<undef> on failure. | |
1234 | ||
41cd218c | 1235 | =item C<offsetof> |
37120919 | 1236 | |
4d0de388 | 1237 | Not implemented. C<offsetof()> is C-specific, you probably want to see L<perlfunc/pack> instead. |
37120919 | 1238 | |
41cd218c | 1239 | =item C<open> |
37120919 | 1240 | |
cb1a09d0 AD |
1241 | Open a file for reading for writing. This returns file descriptors, not |
1242 | Perl filehandles. Use C<POSIX::close> to close the file. | |
1243 | ||
1244 | Open a file read-only with mode 0666. | |
1245 | ||
1246 | $fd = POSIX::open( "foo" ); | |
1247 | ||
1248 | Open a file for read and write. | |
1249 | ||
1250 | $fd = POSIX::open( "foo", &POSIX::O_RDWR ); | |
1251 | ||
1252 | Open a file for write, with truncation. | |
1253 | ||
b70c169c FC |
1254 | $fd = POSIX::open( |
1255 | "foo", &POSIX::O_WRONLY | &POSIX::O_TRUNC | |
1256 | ); | |
cb1a09d0 AD |
1257 | |
1258 | Create a new file with mode 0640. Set up the file for writing. | |
1259 | ||
b70c169c FC |
1260 | $fd = POSIX::open( |
1261 | "foo", &POSIX::O_CREAT | &POSIX::O_WRONLY, 0640 | |
1262 | ); | |
37120919 AD |
1263 | |
1264 | Returns C<undef> on failure. | |
1265 | ||
4755096e GS |
1266 | See also L<perlfunc/sysopen>. |
1267 | ||
41cd218c | 1268 | =item C<opendir> |
37120919 | 1269 | |
cb1a09d0 AD |
1270 | Open a directory for reading. |
1271 | ||
2359510d | 1272 | $dir = POSIX::opendir( "/var" ); |
cb1a09d0 AD |
1273 | @files = POSIX::readdir( $dir ); |
1274 | POSIX::closedir( $dir ); | |
1275 | ||
1276 | Returns C<undef> on failure. | |
37120919 | 1277 | |
41cd218c | 1278 | =item C<pathconf> |
37120919 AD |
1279 | |
1280 | Retrieves the value of a configurable limit on a file or directory. | |
1281 | ||
1282 | The following will determine the maximum length of the longest allowable | |
2359510d | 1283 | pathname on the filesystem which holds C</var>. |
37120919 | 1284 | |
b70c169c FC |
1285 | $path_max = POSIX::pathconf( "/var", |
1286 | &POSIX::_PC_PATH_MAX ); | |
37120919 AD |
1287 | |
1288 | Returns C<undef> on failure. | |
1289 | ||
41cd218c | 1290 | =item C<pause> |
37120919 | 1291 | |
4755096e GS |
1292 | This is similar to the C function C<pause()>, which suspends |
1293 | the execution of the current process until a signal is received. | |
37120919 AD |
1294 | |
1295 | Returns C<undef> on failure. | |
1296 | ||
41cd218c | 1297 | =item C<perror> |
37120919 | 1298 | |
4755096e | 1299 | This is identical to the C function C<perror()>, which outputs to the |
41cd218c | 1300 | standard error stream the specified message followed by C<": "> and the |
4755096e GS |
1301 | current error string. Use the C<warn()> function and the C<$!> |
1302 | variable instead, see L<perlfunc/warn> and L<perlvar/$ERRNO>. | |
37120919 | 1303 | |
41cd218c | 1304 | =item C<pipe> |
37120919 | 1305 | |
cb1a09d0 AD |
1306 | Create an interprocess channel. This returns file descriptors like those |
1307 | returned by C<POSIX::open>. | |
1308 | ||
b27d06da MS |
1309 | my ($read, $write) = POSIX::pipe(); |
1310 | POSIX::write( $write, "hello", 5 ); | |
1311 | POSIX::read( $read, $buf, 5 ); | |
37120919 | 1312 | |
4755096e GS |
1313 | See also L<perlfunc/pipe>. |
1314 | ||
41cd218c | 1315 | =item C<pow> |
37120919 | 1316 | |
4755096e | 1317 | Computes C<$x> raised to the power C<$exponent>. |
37120919 AD |
1318 | |
1319 | $ret = POSIX::pow( $x, $exponent ); | |
1320 | ||
4755096e GS |
1321 | You can also use the C<**> operator, see L<perlop>. |
1322 | ||
41cd218c | 1323 | =item C<printf> |
37120919 | 1324 | |
4d0de388 | 1325 | Formats and prints the specified arguments to C<STDOUT>. |
4755096e | 1326 | See also L<perlfunc/printf>. |
37120919 | 1327 | |
41cd218c | 1328 | =item C<putc> |
37120919 | 1329 | |
4d0de388 | 1330 | Not implemented. C<putc()> is C-specific, see L<perlfunc/print> instead. |
37120919 | 1331 | |
41cd218c | 1332 | =item C<putchar> |
37120919 | 1333 | |
4d0de388 | 1334 | Not implemented. C<putchar()> is C-specific, see L<perlfunc/print> instead. |
37120919 | 1335 | |
41cd218c | 1336 | =item C<puts> |
37120919 | 1337 | |
4d0de388 | 1338 | Not implemented. C<puts()> is C-specific, see L<perlfunc/print> instead. |
37120919 | 1339 | |
41cd218c | 1340 | =item C<qsort> |
37120919 | 1341 | |
4d0de388 | 1342 | Not implemented. C<qsort()> is C-specific, see L<perlfunc/sort> instead. |
37120919 | 1343 | |
41cd218c | 1344 | =item C<raise> |
37120919 AD |
1345 | |
1346 | Sends the specified signal to the current process. | |
4755096e | 1347 | See also L<perlfunc/kill> and the C<$$> in L<perlvar/$PID>. |
37120919 | 1348 | |
41cd218c | 1349 | =item C<rand> |
37120919 | 1350 | |
4d0de388 | 1351 | Not implemented. C<rand()> is non-portable, see L<perlfunc/rand> instead. |
37120919 | 1352 | |
41cd218c | 1353 | =item C<read> |
37120919 | 1354 | |
cb1a09d0 AD |
1355 | Read from a file. This uses file descriptors such as those obtained by |
1356 | calling C<POSIX::open>. If the buffer C<$buf> is not large enough for the | |
1357 | read then Perl will extend it to make room for the request. | |
1358 | ||
1359 | $fd = POSIX::open( "foo", &POSIX::O_RDONLY ); | |
1360 | $bytes = POSIX::read( $fd, $buf, 3 ); | |
37120919 AD |
1361 | |
1362 | Returns C<undef> on failure. | |
1363 | ||
4755096e GS |
1364 | See also L<perlfunc/sysread>. |
1365 | ||
41cd218c | 1366 | =item C<readdir> |
37120919 | 1367 | |
4755096e GS |
1368 | This is identical to Perl's builtin C<readdir()> function |
1369 | for reading directory entries, see L<perlfunc/readdir>. | |
37120919 | 1370 | |
41cd218c | 1371 | =item C<realloc> |
37120919 | 1372 | |
4d0de388 | 1373 | Not implemented. C<realloc()> is C-specific. Perl does memory management transparently. |
37120919 | 1374 | |
9d233e12 JH |
1375 | =item C<remainder> |
1376 | ||
4d0de388 | 1377 | Given C<x> and C<y>, returns the value S<C<x - n*y>>, where C<n> is the integer |
56966515 | 1378 | closest to C<x>/C<y>. [C99] |
4d0de388 KW |
1379 | |
1380 | my $remainder = POSIX::remainder($x, $y) | |
9d233e12 JH |
1381 | |
1382 | See also L</remquo>. | |
1383 | ||
41cd218c | 1384 | =item C<remove> |
37120919 | 1385 | |
c6f0b8ca TC |
1386 | Deletes a name from the filesystem. Calls L<perlfunc/unlink> for |
1387 | files and L<perlfunc/rmdir> for directories. | |
37120919 | 1388 | |
9d233e12 JH |
1389 | =item C<remquo> |
1390 | ||
1391 | Like L</remainder> but also returns the low-order bits of the quotient (n) | |
1392 | [C99] | |
1393 | ||
1394 | (This is quite esoteric interface, mainly used to implement numerical | |
1395 | algorithms.) | |
1396 | ||
41cd218c | 1397 | =item C<rename> |
37120919 | 1398 | |
4755096e GS |
1399 | This is identical to Perl's builtin C<rename()> function |
1400 | for renaming files, see L<perlfunc/rename>. | |
37120919 | 1401 | |
41cd218c | 1402 | =item C<rewind> |
37120919 AD |
1403 | |
1404 | Seeks to the beginning of the file. | |
1405 | ||
41cd218c | 1406 | =item C<rewinddir> |
37120919 | 1407 | |
4755096e GS |
1408 | This is identical to Perl's builtin C<rewinddir()> function for |
1409 | rewinding directory entry streams, see L<perlfunc/rewinddir>. | |
37120919 | 1410 | |
9d233e12 JH |
1411 | =item C<rint> |
1412 | ||
1413 | Identical to L</lrint>. | |
1414 | ||
41cd218c | 1415 | =item C<rmdir> |
37120919 | 1416 | |
4755096e GS |
1417 | This is identical to Perl's builtin C<rmdir()> function |
1418 | for removing (empty) directories, see L<perlfunc/rmdir>. | |
37120919 | 1419 | |
9d233e12 JH |
1420 | =item C<round> |
1421 | ||
9e010b89 JH |
1422 | Returns the integer (but still as floating point) nearest to the |
1423 | argument [C99]. | |
9d233e12 | 1424 | |
351ab2ad | 1425 | See also L</ceil>, L</floor>, L</lround>, L</modf>, and L</trunc>. |
9d233e12 JH |
1426 | |
1427 | =item C<scalbn> | |
1428 | ||
4d0de388 | 1429 | Returns S<C<x * 2**y>> [C99]. |
9d233e12 JH |
1430 | |
1431 | See also L</frexp> and L</ldexp>. | |
1432 | ||
41cd218c | 1433 | =item C<scanf> |
37120919 | 1434 | |
4d0de388 | 1435 | Not implemented. C<scanf()> is C-specific, use E<lt>E<gt> and regular expressions instead, |
4755096e | 1436 | see L<perlre>. |
37120919 | 1437 | |
41cd218c | 1438 | =item C<setgid> |
37120919 | 1439 | |
a043a685 GW |
1440 | Sets the real group identifier and the effective group identifier for |
1441 | this process. Similar to assigning a value to the Perl's builtin | |
2bc0d022 | 1442 | C<$)> variable, see L<perlvar/$EGID>, except that the latter |
a043a685 GW |
1443 | will change only the real user identifier, and that the setgid() |
1444 | uses only a single numeric argument, as opposed to a space-separated | |
1445 | list of numbers. | |
37120919 | 1446 | |
41cd218c | 1447 | =item C<setjmp> |
37120919 | 1448 | |
4d0de388 | 1449 | Not implemented. C<setjmp()> is C-specific: use C<eval {}> instead, |
4755096e | 1450 | see L<perlfunc/eval>. |
37120919 | 1451 | |
41cd218c | 1452 | =item C<setlocale> |
37120919 | 1453 | |
06283613 KW |
1454 | WARNING! Prior to Perl 5.28 or on a system that does not support |
1455 | thread-safe locale operations, do NOT use this function in a | |
1456 | L<thread|threads>. The locale will change in all other threads at the | |
1457 | same time, and should your thread get paused by the operating system, | |
1458 | and another started, that thread will not have the locale it is | |
1459 | expecting. On some platforms, there can be a race leading to segfaults | |
1460 | if two threads call this function nearly simultaneously. On unthreaded | |
1461 | builds, or on Perl 5.28 and later on thread-safe systems, this warning | |
1462 | does not apply. | |
1463 | ||
1464 | This function | |
1465 | modifies and queries the program's underlying locale. Users of this | |
dfcc8045 KW |
1466 | function should read L<perllocale>, whch provides a comprehensive |
1467 | discussion of Perl locale handling, knowledge of which is necessary to | |
1468 | properly use this function. It contains | |
1469 | L<a section devoted to this function|perllocale/The setlocale function>. | |
1470 | The discussion here is merely a summary reference for C<setlocale()>. | |
6ea81ccf KW |
1471 | Note that Perl itself is almost entirely unaffected by the locale |
1472 | except within the scope of S<C<"use locale">>. (Exceptions are listed | |
06283613 KW |
1473 | in L<perllocale/Not within the scope of "use locale">, and |
1474 | locale-dependent functions within the POSIX module ARE always affected | |
1475 | by the current locale.) | |
6ea81ccf KW |
1476 | |
1477 | The following examples assume | |
c26abfa6 JH |
1478 | |
1479 | use POSIX qw(setlocale LC_ALL LC_CTYPE); | |
1480 | ||
1481 | has been issued. | |
37120919 | 1482 | |
8966fa01 JH |
1483 | The following will set the traditional UNIX system locale behavior |
1484 | (the second argument C<"C">). | |
37120919 | 1485 | |
c26abfa6 | 1486 | $loc = setlocale( LC_ALL, "C" ); |
37120919 | 1487 | |
41cd218c | 1488 | The following will query the current C<LC_CTYPE> category. (No second |
c26abfa6 | 1489 | argument means 'query'.) |
8966fa01 | 1490 | |
c26abfa6 | 1491 | $loc = setlocale( LC_CTYPE ); |
8966fa01 | 1492 | |
41cd218c | 1493 | The following will set the C<LC_CTYPE> behaviour according to the locale |
8966fa01 | 1494 | environment variables (the second argument C<"">). |
4c9b78f4 | 1495 | Please see your system's C<setlocale(3)> documentation for the locale |
71be2cbc | 1496 | environment variables' meaning or consult L<perllocale>. |
8966fa01 | 1497 | |
c26abfa6 | 1498 | $loc = setlocale( LC_CTYPE, "" ); |
8966fa01 | 1499 | |
41cd218c | 1500 | The following will set the C<LC_COLLATE> behaviour to Argentinian |
8966fa01 | 1501 | Spanish. B<NOTE>: The naming and availability of locales depends on |
71be2cbc | 1502 | your operating system. Please consult L<perllocale> for how to find |
8966fa01 JH |
1503 | out which locales are available in your system. |
1504 | ||
801ed997 | 1505 | $loc = setlocale( LC_COLLATE, "es_AR.ISO8859-1" ); |
8966fa01 | 1506 | |
07bb61ac JH |
1507 | =item C<setpayload> |
1508 | ||
1509 | use POSIX ':nan_payload'; | |
1510 | setpayload($var, $payload); | |
1511 | ||
1512 | Sets the C<NaN> payload of var. | |
1513 | ||
1514 | NOTE: the NaN payload APIs are based on the latest (as of June 2015) | |
1515 | proposed ISO C interfaces, but they are not yet a standard. Things | |
1516 | may change. | |
1517 | ||
1518 | See L</nan> for more discussion about C<NaN>. | |
1519 | ||
1520 | See also L</setpayloadsig>, L</isnan>, L</getpayload>, and L</issignaling>. | |
1521 | ||
1522 | =item C<setpayloadsig> | |
1523 | ||
1524 | use POSIX ':nan_payload'; | |
1525 | setpayloadsig($var, $payload); | |
1526 | ||
1527 | Like L</setpayload> but also makes the NaN I<signaling>. | |
1528 | ||
1529 | Depending on the platform the NaN may or may not behave differently. | |
1530 | ||
1531 | Note the API instability warning in L</setpayload>. | |
1532 | ||
1533 | Note that because how the floating point formats work out, on the most | |
1534 | common platforms signaling payload of zero is best avoided, | |
1535 | since it might end up being identical to C<+Inf>. | |
1536 | ||
1537 | See also L</nan>, L</isnan>, L</getpayload>, and L</issignaling>. | |
1538 | ||
41cd218c | 1539 | =item C<setpgid> |
37120919 | 1540 | |
4755096e GS |
1541 | This is similar to the C function C<setpgid()> for |
1542 | setting the process group identifier of the current process. | |
37120919 AD |
1543 | |
1544 | Returns C<undef> on failure. | |
1545 | ||
41cd218c | 1546 | =item C<setsid> |
37120919 | 1547 | |
4755096e GS |
1548 | This is identical to the C function C<setsid()> for |
1549 | setting the session identifier of the current process. | |
37120919 | 1550 | |
41cd218c | 1551 | =item C<setuid> |
37120919 | 1552 | |
a043a685 GW |
1553 | Sets the real user identifier and the effective user identifier for |
1554 | this process. Similar to assigning a value to the Perl's builtin | |
1555 | C<$E<lt>> variable, see L<perlvar/$UID>, except that the latter | |
1556 | will change only the real user identifier. | |
37120919 | 1557 | |
41cd218c | 1558 | =item C<sigaction> |
37120919 | 1559 | |
3609ea0d JH |
1560 | Detailed signal management. This uses C<POSIX::SigAction> objects for |
1561 | the C<action> and C<oldaction> arguments (the oldaction can also be | |
1562 | just a hash reference). Consult your system's C<sigaction> manpage | |
1563 | for details, see also C<POSIX::SigRt>. | |
cb1a09d0 AD |
1564 | |
1565 | Synopsis: | |
1566 | ||
1d81eac9 | 1567 | sigaction(signal, action, oldaction = 0) |
37120919 | 1568 | |
1d81eac9 | 1569 | Returns C<undef> on failure. The C<signal> must be a number (like |
41cd218c | 1570 | C<SIGHUP>), not a string (like C<"SIGHUP">), though Perl does try hard |
1d81eac9 | 1571 | to understand you. |
37120919 | 1572 | |
41cd218c | 1573 | If you use the C<SA_SIGINFO> flag, the signal handler will in addition to |
8aad04aa JH |
1574 | the first argument, the signal name, also receive a second argument, a |
1575 | hash reference, inside which are the following keys with the following | |
1576 | semantics, as defined by POSIX/SUSv3: | |
1577 | ||
1578 | signo the signal number | |
1579 | errno the error number | |
1580 | code if this is zero or less, the signal was sent by | |
1581 | a user process and the uid and pid make sense, | |
1582 | otherwise the signal was sent by the kernel | |
79dec0f4 | 1583 | |
34e79b75 DIM |
1584 | The constants for specific C<code> values can be imported individually |
1585 | or using the C<:signal_h_si_code> tag. | |
1586 | ||
79dec0f4 JH |
1587 | The following are also defined by POSIX/SUSv3, but unfortunately |
1588 | not very widely implemented: | |
1589 | ||
8aad04aa JH |
1590 | pid the process id generating the signal |
1591 | uid the uid of the process id generating the signal | |
1592 | status exit value or signal for SIGCHLD | |
1593 | band band event for SIGPOLL | |
408b5f5e KW |
1594 | addr address of faulting instruction or memory |
1595 | reference for SIGILL, SIGFPE, SIGSEGV or SIGBUS | |
8aad04aa JH |
1596 | |
1597 | A third argument is also passed to the handler, which contains a copy | |
41cd218c KW |
1598 | of the raw binary contents of the C<siginfo> structure: if a system has |
1599 | some non-POSIX fields, this third argument is where to C<unpack()> them | |
8aad04aa JH |
1600 | from. |
1601 | ||
41cd218c | 1602 | Note that not all C<siginfo> values make sense simultaneously (some are |
8aad04aa JH |
1603 | valid only for certain signals, for example), and not all values make |
1604 | sense from Perl perspective, you should to consult your system's | |
1605 | C<sigaction> and possibly also C<siginfo> documentation. | |
1606 | ||
41cd218c | 1607 | =item C<siglongjmp> |
37120919 | 1608 | |
4d0de388 | 1609 | Not implemented. C<siglongjmp()> is C-specific: use L<perlfunc/die> instead. |
37120919 | 1610 | |
9d233e12 JH |
1611 | =item C<signbit> |
1612 | ||
1613 | Returns zero for positive arguments, non-zero for negative arguments [C99]. | |
1614 | ||
41cd218c | 1615 | =item C<sigpending> |
37120919 | 1616 | |
cb1a09d0 AD |
1617 | Examine signals that are blocked and pending. This uses C<POSIX::SigSet> |
1618 | objects for the C<sigset> argument. Consult your system's C<sigpending> | |
1619 | manpage for details. | |
1620 | ||
1621 | Synopsis: | |
1622 | ||
1623 | sigpending(sigset) | |
37120919 AD |
1624 | |
1625 | Returns C<undef> on failure. | |
1626 | ||
41cd218c | 1627 | =item C<sigprocmask> |
37120919 | 1628 | |
cb1a09d0 AD |
1629 | Change and/or examine calling process's signal mask. This uses |
1630 | C<POSIX::SigSet> objects for the C<sigset> and C<oldsigset> arguments. | |
1631 | Consult your system's C<sigprocmask> manpage for details. | |
1632 | ||
1633 | Synopsis: | |
1634 | ||
1635 | sigprocmask(how, sigset, oldsigset = 0) | |
37120919 AD |
1636 | |
1637 | Returns C<undef> on failure. | |
1638 | ||
faaf6836 LT |
1639 | Note that you can't reliably block or unblock a signal from its own signal |
1640 | handler if you're using safe signals. Other signals can be blocked or unblocked | |
1641 | reliably. | |
1642 | ||
41cd218c | 1643 | =item C<sigsetjmp> |
37120919 | 1644 | |
4d0de388 | 1645 | Not implemented. C<sigsetjmp()> is C-specific: use C<eval {}> instead, |
4755096e | 1646 | see L<perlfunc/eval>. |
37120919 | 1647 | |
41cd218c | 1648 | =item C<sigsuspend> |
37120919 | 1649 | |
cb1a09d0 AD |
1650 | Install a signal mask and suspend process until signal arrives. This uses |
1651 | C<POSIX::SigSet> objects for the C<signal_mask> argument. Consult your | |
1652 | system's C<sigsuspend> manpage for details. | |
1653 | ||
1654 | Synopsis: | |
1655 | ||
1656 | sigsuspend(signal_mask) | |
37120919 AD |
1657 | |
1658 | Returns C<undef> on failure. | |
1659 | ||
41cd218c | 1660 | =item C<sin> |
37120919 | 1661 | |
4755096e GS |
1662 | This is identical to Perl's builtin C<sin()> function |
1663 | for returning the sine of the numerical argument, | |
c2e66d9e | 1664 | see L<perlfunc/sin>. See also L<Math::Trig>. |
37120919 | 1665 | |
41cd218c | 1666 | =item C<sinh> |
37120919 | 1667 | |
4755096e GS |
1668 | This is identical to the C function C<sinh()> |
1669 | for returning the hyperbolic sine of the numerical argument. | |
c2e66d9e | 1670 | See also L<Math::Trig>. |
37120919 | 1671 | |
41cd218c | 1672 | =item C<sleep> |
37120919 | 1673 | |
2ab27a20 A |
1674 | This is functionally identical to Perl's builtin C<sleep()> function |
1675 | for suspending the execution of the current for process for certain | |
3609ea0d | 1676 | number of seconds, see L<perlfunc/sleep>. There is one significant |
2bad225e | 1677 | difference, however: C<POSIX::sleep()> returns the number of |
2ab27a20 A |
1678 | B<unslept> seconds, while the C<CORE::sleep()> returns the |
1679 | number of slept seconds. | |
37120919 | 1680 | |
41cd218c | 1681 | =item C<sprintf> |
37120919 | 1682 | |
4755096e GS |
1683 | This is similar to Perl's builtin C<sprintf()> function |
1684 | for returning a string that has the arguments formatted as requested, | |
1685 | see L<perlfunc/sprintf>. | |
37120919 | 1686 | |
41cd218c | 1687 | =item C<sqrt> |
37120919 AD |
1688 | |
1689 | This is identical to Perl's builtin C<sqrt()> function. | |
4755096e GS |
1690 | for returning the square root of the numerical argument, |
1691 | see L<perlfunc/sqrt>. | |
37120919 | 1692 | |
41cd218c | 1693 | =item C<srand> |
37120919 | 1694 | |
4755096e | 1695 | Give a seed the pseudorandom number generator, see L<perlfunc/srand>. |
37120919 | 1696 | |
41cd218c | 1697 | =item C<sscanf> |
37120919 | 1698 | |
4d0de388 | 1699 | Not implemented. C<sscanf()> is C-specific, use regular expressions instead, |
4755096e | 1700 | see L<perlre>. |
37120919 | 1701 | |
41cd218c | 1702 | =item C<stat> |
37120919 | 1703 | |
4755096e | 1704 | This is identical to Perl's builtin C<stat()> function |
d7f8936a | 1705 | for returning information about files and directories. |
37120919 | 1706 | |
41cd218c | 1707 | =item C<strcat> |
37120919 | 1708 | |
4d0de388 | 1709 | Not implemented. C<strcat()> is C-specific, use C<.=> instead, see L<perlop>. |
37120919 | 1710 | |
41cd218c | 1711 | =item C<strchr> |
37120919 | 1712 | |
4d0de388 | 1713 | Not implemented. C<strchr()> is C-specific, see L<perlfunc/index> instead. |
37120919 | 1714 | |
41cd218c | 1715 | =item C<strcmp> |
37120919 | 1716 | |
4d0de388 | 1717 | Not implemented. C<strcmp()> is C-specific, use C<eq> or C<cmp> instead, see L<perlop>. |
37120919 | 1718 | |
41cd218c | 1719 | =item C<strcoll> |
37120919 | 1720 | |
4755096e GS |
1721 | This is identical to the C function C<strcoll()> |
1722 | for collating (comparing) strings transformed using | |
1723 | the C<strxfrm()> function. Not really needed since | |
1724 | Perl can do this transparently, see L<perllocale>. | |
37120919 | 1725 | |
393aa92a KW |
1726 | Beware that in a UTF-8 locale, anything you pass to this function must |
1727 | be in UTF-8; and when not in a UTF-8 locale, anything passed must not be | |
1728 | UTF-8 encoded. | |
1729 | ||
41cd218c | 1730 | =item C<strcpy> |
37120919 | 1731 | |
4d0de388 | 1732 | Not implemented. C<strcpy()> is C-specific, use C<=> instead, see L<perlop>. |
37120919 | 1733 | |
41cd218c | 1734 | =item C<strcspn> |
37120919 | 1735 | |
4d0de388 | 1736 | Not implemented. C<strcspn()> is C-specific, use regular expressions instead, |
4755096e | 1737 | see L<perlre>. |
37120919 | 1738 | |
41cd218c | 1739 | =item C<strerror> |
37120919 AD |
1740 | |
1741 | Returns the error string for the specified errno. | |
4d0de388 | 1742 | Identical to the string form of C<$!>, see L<perlvar/$ERRNO>. |
37120919 | 1743 | |
41cd218c | 1744 | =item C<strftime> |
37120919 | 1745 | |
cb1a09d0 AD |
1746 | Convert date and time information to string. Returns the string. |
1747 | ||
1748 | Synopsis: | |
1749 | ||
b70c169c FC |
1750 | strftime(fmt, sec, min, hour, mday, mon, year, |
1751 | wday = -1, yday = -1, isdst = -1) | |
cb1a09d0 | 1752 | |
4d0de388 KW |
1753 | The month (C<mon>), weekday (C<wday>), and yearday (C<yday>) begin at zero, |
1754 | I<i.e.>, January is 0, not 1; Sunday is 0, not 1; January 1st is 0, not 1. The | |
1755 | year (C<year>) is given in years since 1900, I<i.e.>, the year 1995 is 95; the | |
cb1a09d0 | 1756 | year 2001 is 101. Consult your system's C<strftime()> manpage for details |
659b4938 | 1757 | about these and the other arguments. |
f14c76ed | 1758 | |
659b4938 DD |
1759 | If you want your code to be portable, your format (C<fmt>) argument |
1760 | should use only the conversion specifiers defined by the ANSI C | |
f14c76ed RGS |
1761 | standard (C89, to play safe). These are C<aAbBcdHIjmMpSUwWxXyYZ%>. |
1762 | But even then, the B<results> of some of the conversion specifiers are | |
1763 | non-portable. For example, the specifiers C<aAbBcpZ> change according | |
1764 | to the locale settings of the user, and both how to set locales (the | |
1765 | locale names) and what output to expect are non-standard. | |
1766 | The specifier C<c> changes according to the timezone settings of the | |
1767 | user and the timezone computation rules of the operating system. | |
1768 | The C<Z> specifier is notoriously unportable since the names of | |
1769 | timezones are non-standard. Sticking to the numeric specifiers is the | |
1770 | safest route. | |
1771 | ||
1772 | The given arguments are made consistent as though by calling | |
1773 | C<mktime()> before calling your system's C<strftime()> function, | |
1774 | except that the C<isdst> value is not affected. | |
cb1a09d0 AD |
1775 | |
1776 | The string for Tuesday, December 12, 1995. | |
1777 | ||
b70c169c FC |
1778 | $str = POSIX::strftime( "%A, %B %d, %Y", |
1779 | 0, 0, 0, 12, 11, 95, 2 ); | |
cb1a09d0 | 1780 | print "$str\n"; |
37120919 | 1781 | |
41cd218c | 1782 | =item C<strlen> |
37120919 | 1783 | |
4d0de388 | 1784 | Not implemented. C<strlen()> is C-specific, use C<length()> instead, see L<perlfunc/length>. |
37120919 | 1785 | |
41cd218c | 1786 | =item C<strncat> |
37120919 | 1787 | |
4d0de388 | 1788 | Not implemented. C<strncat()> is C-specific, use C<.=> instead, see L<perlop>. |
37120919 | 1789 | |
41cd218c | 1790 | =item C<strncmp> |
37120919 | 1791 | |
4d0de388 | 1792 | Not implemented. C<strncmp()> is C-specific, use C<eq> instead, see L<perlop>. |
37120919 | 1793 | |
41cd218c | 1794 | =item C<strncpy> |
37120919 | 1795 | |
4d0de388 | 1796 | Not implemented. C<strncpy()> is C-specific, use C<=> instead, see L<perlop>. |
37120919 | 1797 | |
41cd218c | 1798 | =item C<strpbrk> |
37120919 | 1799 | |
4d0de388 | 1800 | Not implemented. C<strpbrk()> is C-specific, use regular expressions instead, |
4755096e | 1801 | see L<perlre>. |
37120919 | 1802 | |
41cd218c | 1803 | =item C<strrchr> |
37120919 | 1804 | |
4d0de388 | 1805 | Not implemented. C<strrchr()> is C-specific, see L<perlfunc/rindex> instead. |
37120919 | 1806 | |
41cd218c | 1807 | =item C<strspn> |
37120919 | 1808 | |
4d0de388 | 1809 | Not implemented. C<strspn()> is C-specific, use regular expressions instead, |
4755096e | 1810 | see L<perlre>. |
37120919 | 1811 | |
41cd218c | 1812 | =item C<strstr> |
37120919 | 1813 | |
4755096e GS |
1814 | This is identical to Perl's builtin C<index()> function, |
1815 | see L<perlfunc/index>. | |
37120919 | 1816 | |
41cd218c | 1817 | =item C<strtod> |
37120919 | 1818 | |
a89d8a78 DH |
1819 | String to double translation. Returns the parsed number and the number |
1820 | of characters in the unparsed portion of the string. Truly | |
41cd218c | 1821 | POSIX-compliant systems set C<$!> (C<$ERRNO>) to indicate a translation |
4d0de388 | 1822 | error, so clear C<$!> before calling C<strtod>. However, non-POSIX systems |
41cd218c | 1823 | may not check for overflow, and therefore will never set C<$!>. |
a89d8a78 | 1824 | |
4e6effb7 | 1825 | C<strtod> respects any POSIX C<setlocale()> C<LC_NUMERIC> settings, |
458680b3 | 1826 | regardless of whether or not it is called from Perl code that is within |
aa2bc4d3 KW |
1827 | the scope of S<C<use locale>>. This means it should not be used in a |
1828 | threaded application unless it's certain that the underlying locale is C | |
1829 | or POSIX. This is because it otherwise changes the locale, which | |
1830 | globally affects all threads simultaneously. | |
a89d8a78 | 1831 | |
41cd218c | 1832 | To parse a string C<$str> as a floating point number use |
a89d8a78 DH |
1833 | |
1834 | $! = 0; | |
1835 | ($num, $n_unparsed) = POSIX::strtod($str); | |
1836 | ||
41cd218c | 1837 | The second returned item and C<$!> can be used to check for valid input: |
a89d8a78 | 1838 | |
6309100e DM |
1839 | if (($str eq '') || ($n_unparsed != 0) || $!) { |
1840 | die "Non-numeric input $str" . ($! ? ": $!\n" : "\n"); | |
a89d8a78 DH |
1841 | } |
1842 | ||
4d0de388 | 1843 | When called in a scalar context C<strtod> returns the parsed number. |
37120919 | 1844 | |
41cd218c | 1845 | =item C<strtok> |
37120919 | 1846 | |
4d0de388 | 1847 | Not implemented. C<strtok()> is C-specific, use regular expressions instead, see |
4755096e | 1848 | L<perlre>, or L<perlfunc/split>. |
37120919 | 1849 | |
41cd218c | 1850 | =item C<strtol> |
37120919 | 1851 | |
a89d8a78 DH |
1852 | String to (long) integer translation. Returns the parsed number and |
1853 | the number of characters in the unparsed portion of the string. Truly | |
41cd218c KW |
1854 | POSIX-compliant systems set C<$!> (C<$ERRNO>) to indicate a translation |
1855 | error, so clear C<$!> before calling C<strtol>. However, non-POSIX systems | |
1856 | may not check for overflow, and therefore will never set C<$!>. | |
a89d8a78 | 1857 | |
41cd218c | 1858 | C<strtol> should respect any POSIX I<setlocale()> settings. |
a89d8a78 | 1859 | |
41cd218c | 1860 | To parse a string C<$str> as a number in some base C<$base> use |
a89d8a78 DH |
1861 | |
1862 | $! = 0; | |
1863 | ($num, $n_unparsed) = POSIX::strtol($str, $base); | |
1864 | ||
1865 | The base should be zero or between 2 and 36, inclusive. When the base | |
4d0de388 | 1866 | is zero or omitted C<strtol> will use the string itself to determine the |
a89d8a78 DH |
1867 | base: a leading "0x" or "0X" means hexadecimal; a leading "0" means |
1868 | octal; any other leading characters mean decimal. Thus, "1234" is | |
1869 | parsed as a decimal number, "01234" as an octal number, and "0x1234" | |
1870 | as a hexadecimal number. | |
1871 | ||
41cd218c | 1872 | The second returned item and C<$!> can be used to check for valid input: |
a89d8a78 DH |
1873 | |
1874 | if (($str eq '') || ($n_unparsed != 0) || !$!) { | |
1875 | die "Non-numeric input $str" . $! ? ": $!\n" : "\n"; | |
1876 | } | |
1877 | ||
4d0de388 | 1878 | When called in a scalar context C<strtol> returns the parsed number. |
a89d8a78 | 1879 | |
0ff7b9da JH |
1880 | =item C<strtold> |
1881 | ||
1882 | Like L</strtod> but for long doubles. Defined only if the | |
1883 | system supports long doubles. | |
1884 | ||
41cd218c | 1885 | =item C<strtoul> |
a89d8a78 | 1886 | |
41cd218c KW |
1887 | String to unsigned (long) integer translation. C<strtoul()> is identical |
1888 | to C<strtol()> except that C<strtoul()> only parses unsigned integers. See | |
4755096e | 1889 | L</strtol> for details. |
a89d8a78 | 1890 | |
41cd218c KW |
1891 | Note: Some vendors supply C<strtod()> and C<strtol()> but not C<strtoul()>. |
1892 | Other vendors that do supply C<strtoul()> parse "-1" as a valid value. | |
37120919 | 1893 | |
41cd218c | 1894 | =item C<strxfrm> |
37120919 | 1895 | |
cb1a09d0 AD |
1896 | String transformation. Returns the transformed string. |
1897 | ||
1898 | $dst = POSIX::strxfrm( $src ); | |
37120919 | 1899 | |
4755096e GS |
1900 | Used in conjunction with the C<strcoll()> function, see L</strcoll>. |
1901 | ||
1902 | Not really needed since Perl can do this transparently, see | |
1903 | L<perllocale>. | |
1904 | ||
393aa92a KW |
1905 | Beware that in a UTF-8 locale, anything you pass to this function must |
1906 | be in UTF-8; and when not in a UTF-8 locale, anything passed must not be | |
1907 | UTF-8 encoded. | |
1908 | ||
41cd218c | 1909 | =item C<sysconf> |
37120919 AD |
1910 | |
1911 | Retrieves values of system configurable variables. | |
1912 | ||
1913 | The following will get the machine's clock speed. | |
1914 | ||
1915 | $clock_ticks = POSIX::sysconf( &POSIX::_SC_CLK_TCK ); | |
1916 | ||
1917 | Returns C<undef> on failure. | |
1918 | ||
41cd218c | 1919 | =item C<system> |
37120919 | 1920 | |
4755096e GS |
1921 | This is identical to Perl's builtin C<system()> function, see |
1922 | L<perlfunc/system>. | |
37120919 | 1923 | |
41cd218c | 1924 | =item C<tan> |
37120919 | 1925 | |
4755096e | 1926 | This is identical to the C function C<tan()>, returning the |
c2e66d9e | 1927 | tangent of the numerical argument. See also L<Math::Trig>. |
37120919 | 1928 | |
41cd218c | 1929 | =item C<tanh> |
37120919 | 1930 | |
4755096e | 1931 | This is identical to the C function C<tanh()>, returning the |
c2e66d9e | 1932 | hyperbolic tangent of the numerical argument. See also L<Math::Trig>. |
37120919 | 1933 | |
41cd218c | 1934 | =item C<tcdrain> |
37120919 | 1935 | |
4755096e GS |
1936 | This is similar to the C function C<tcdrain()> for draining |
1937 | the output queue of its argument stream. | |
37120919 AD |
1938 | |
1939 | Returns C<undef> on failure. | |
1940 | ||
41cd218c | 1941 | =item C<tcflow> |
37120919 | 1942 | |
4755096e GS |
1943 | This is similar to the C function C<tcflow()> for controlling |
1944 | the flow of its argument stream. | |
37120919 AD |
1945 | |
1946 | Returns C<undef> on failure. | |
1947 | ||
41cd218c | 1948 | =item C<tcflush> |
37120919 | 1949 | |
4755096e | 1950 | This is similar to the C function C<tcflush()> for flushing |
cc767757 | 1951 | the I/O buffers of its argument stream. |
37120919 AD |
1952 | |
1953 | Returns C<undef> on failure. | |
1954 | ||
41cd218c | 1955 | =item C<tcgetpgrp> |
37120919 | 1956 | |
4755096e GS |
1957 | This is identical to the C function C<tcgetpgrp()> for returning the |
1958 | process group identifier of the foreground process group of the controlling | |
1959 | terminal. | |
37120919 | 1960 | |
41cd218c | 1961 | =item C<tcsendbreak> |
37120919 | 1962 | |
4755096e GS |
1963 | This is similar to the C function C<tcsendbreak()> for sending |
1964 | a break on its argument stream. | |
37120919 AD |
1965 | |
1966 | Returns C<undef> on failure. | |
1967 | ||
41cd218c | 1968 | =item C<tcsetpgrp> |
37120919 | 1969 | |
4755096e GS |
1970 | This is similar to the C function C<tcsetpgrp()> for setting the |
1971 | process group identifier of the foreground process group of the controlling | |
1972 | terminal. | |
37120919 AD |
1973 | |
1974 | Returns C<undef> on failure. | |
1975 | ||
9d233e12 JH |
1976 | =item C<tgamma> |
1977 | ||
1978 | The Gamma function [C99]. | |
1979 | ||
1980 | See also L</lgamma>. | |
1981 | ||
41cd218c | 1982 | =item C<time> |
37120919 | 1983 | |
4755096e GS |
1984 | This is identical to Perl's builtin C<time()> function |
1985 | for returning the number of seconds since the epoch | |
1986 | (whatever it is for the system), see L<perlfunc/time>. | |
37120919 | 1987 | |
41cd218c | 1988 | =item C<times> |
37120919 | 1989 | |
41cd218c | 1990 | The C<times()> function returns elapsed realtime since some point in the past |
37120919 AD |
1991 | (such as system startup), user and system times for this process, and user |
1992 | and system times used by child processes. All times are returned in clock | |
1993 | ticks. | |
1994 | ||
4d0de388 | 1995 | ($realtime, $user, $system, $cuser, $csystem) |
b70c169c | 1996 | = POSIX::times(); |
37120919 AD |
1997 | |
1998 | Note: Perl's builtin C<times()> function returns four values, measured in | |
1999 | seconds. | |
2000 | ||
41cd218c | 2001 | =item C<tmpfile> |
37120919 | 2002 | |
4d0de388 | 2003 | Not implemented. Use method C<IO::File::new_tmpfile()> instead, or see L<File::Temp>. |
37120919 | 2004 | |
41cd218c | 2005 | =item C<tmpnam> |
37120919 | 2006 | |
60cba15a | 2007 | For security reasons, which are probably detailed in your system's |
41cd218c | 2008 | documentation for the C library C<tmpnam()> function, this interface |
26acb4d0 | 2009 | is no longer available; instead use L<File::Temp>. |
4755096e | 2010 | |
41cd218c | 2011 | =item C<tolower> |
37120919 | 2012 | |
4755096e | 2013 | This is identical to the C function, except that it can apply to a single |
4d0de388 KW |
2014 | character or to a whole string, and currently operates as if the locale |
2015 | always is "C". Consider using the C<lc()> function, see L<perlfunc/lc>, | |
4755096e GS |
2016 | see L<perlfunc/lc>, or the equivalent C<\L> operator inside doublequotish |
2017 | strings. | |
37120919 | 2018 | |
41cd218c | 2019 | =item C<toupper> |
37120919 | 2020 | |
4d0de388 KW |
2021 | This is similar to the C function, except that it can apply to a single |
2022 | character or to a whole string, and currently operates as if the locale | |
2023 | always is "C". Consider using the C<uc()> function, see L<perlfunc/uc>, | |
2024 | or the equivalent C<\U> operator inside doublequotish strings. | |
37120919 | 2025 | |
9d233e12 JH |
2026 | =item C<trunc> |
2027 | ||
2028 | Returns the integer toward zero from the argument [C99]. | |
2029 | ||
2030 | See also L</ceil>, L</floor>, and L</round>. | |
2031 | ||
41cd218c | 2032 | =item C<ttyname> |
37120919 | 2033 | |
4755096e GS |
2034 | This is identical to the C function C<ttyname()> for returning the |
2035 | name of the current terminal. | |
37120919 | 2036 | |
41cd218c | 2037 | =item C<tzname> |
37120919 | 2038 | |
cb1a09d0 AD |
2039 | Retrieves the time conversion information from the C<tzname> variable. |
2040 | ||
2041 | POSIX::tzset(); | |
2042 | ($std, $dst) = POSIX::tzname(); | |
37120919 | 2043 | |
41cd218c | 2044 | =item C<tzset> |
37120919 | 2045 | |
4755096e GS |
2046 | This is identical to the C function C<tzset()> for setting |
2047 | the current timezone based on the environment variable C<TZ>, | |
2048 | to be used by C<ctime()>, C<localtime()>, C<mktime()>, and C<strftime()> | |
2049 | functions. | |
37120919 | 2050 | |
41cd218c | 2051 | =item C<umask> |
37120919 | 2052 | |
4755096e GS |
2053 | This is identical to Perl's builtin C<umask()> function |
2054 | for setting (and querying) the file creation permission mask, | |
2055 | see L<perlfunc/umask>. | |
37120919 | 2056 | |
41cd218c | 2057 | =item C<uname> |
37120919 | 2058 | |
cb1a09d0 AD |
2059 | Get name of current operating system. |
2060 | ||
b70c169c FC |
2061 | ($sysname, $nodename, $release, $version, $machine) |
2062 | = POSIX::uname(); | |
4755096e GS |
2063 | |
2064 | Note that the actual meanings of the various fields are not | |
2065 | that well standardized, do not expect any great portability. | |
2066 | The C<$sysname> might be the name of the operating system, | |
2067 | the C<$nodename> might be the name of the host, the C<$release> | |
2068 | might be the (major) release number of the operating system, | |
2069 | the C<$version> might be the (minor) release number of the | |
2070 | operating system, and the C<$machine> might be a hardware identifier. | |
2071 | Maybe. | |
37120919 | 2072 | |
41cd218c | 2073 | =item C<ungetc> |
37120919 | 2074 | |
4d0de388 | 2075 | Not implemented. Use method C<IO::Handle::ungetc()> instead. |
37120919 | 2076 | |
41cd218c | 2077 | =item C<unlink> |
37120919 | 2078 | |
4755096e GS |
2079 | This is identical to Perl's builtin C<unlink()> function |
2080 | for removing files, see L<perlfunc/unlink>. | |
37120919 | 2081 | |
41cd218c | 2082 | =item C<utime> |
37120919 | 2083 | |
4755096e GS |
2084 | This is identical to Perl's builtin C<utime()> function |
2085 | for changing the time stamps of files and directories, | |
2086 | see L<perlfunc/utime>. | |
37120919 | 2087 | |
41cd218c | 2088 | =item C<vfprintf> |
37120919 | 2089 | |
4d0de388 | 2090 | Not implemented. C<vfprintf()> is C-specific, see L<perlfunc/printf> instead. |
37120919 | 2091 | |
41cd218c | 2092 | =item C<vprintf> |
37120919 | 2093 | |
4d0de388 | 2094 | Not implemented. C<vprintf()> is C-specific, see L<perlfunc/printf> instead. |
37120919 | 2095 | |
41cd218c | 2096 | =item C<vsprintf> |
37120919 | 2097 | |
4d0de388 | 2098 | Not implemented. C<vsprintf()> is C-specific, see L<perlfunc/sprintf> instead. |
37120919 | 2099 | |
41cd218c | 2100 | =item C<wait> |
37120919 | 2101 | |
4755096e GS |
2102 | This is identical to Perl's builtin C<wait()> function, |
2103 | see L<perlfunc/wait>. | |
37120919 | 2104 | |
41cd218c | 2105 | =item C<waitpid> |
37120919 | 2106 | |
cb1a09d0 | 2107 | Wait for a child process to change state. This is identical to Perl's |
4755096e | 2108 | builtin C<waitpid()> function, see L<perlfunc/waitpid>. |
cb1a09d0 | 2109 | |
2ac1ef3d | 2110 | $pid = POSIX::waitpid( -1, POSIX::WNOHANG ); |
cb1a09d0 | 2111 | print "status = ", ($? / 256), "\n"; |
37120919 | 2112 | |
41cd218c | 2113 | =item C<wcstombs> |
37120919 | 2114 | |
cb1a09d0 | 2115 | This is identical to the C function C<wcstombs()>. |
351ab2ad JH |
2116 | |
2117 | See L</mblen>. | |
37120919 | 2118 | |
41cd218c | 2119 | =item C<wctomb> |
37120919 | 2120 | |
cb1a09d0 | 2121 | This is identical to the C function C<wctomb()>. |
351ab2ad JH |
2122 | |
2123 | See L</mblen>. | |
37120919 | 2124 | |
41cd218c | 2125 | =item C<write> |
37120919 | 2126 | |
cb1a09d0 AD |
2127 | Write to a file. This uses file descriptors such as those obtained by |
2128 | calling C<POSIX::open>. | |
2129 | ||
2130 | $fd = POSIX::open( "foo", &POSIX::O_WRONLY ); | |
2131 | $buf = "hello"; | |
a0604b4c | 2132 | $bytes = POSIX::write( $fd, $buf, 5 ); |
37120919 AD |
2133 | |
2134 | Returns C<undef> on failure. | |
2135 | ||
4755096e GS |
2136 | See also L<perlfunc/syswrite>. |
2137 | ||
37120919 AD |
2138 | =back |
2139 | ||
2140 | =head1 CLASSES | |
2141 | ||
41cd218c | 2142 | =head2 C<POSIX::SigAction> |
37120919 AD |
2143 | |
2144 | =over 8 | |
2145 | ||
41cd218c | 2146 | =item C<new> |
37120919 | 2147 | |
cb1a09d0 | 2148 | Creates a new C<POSIX::SigAction> object which corresponds to the C |
3609ea0d JH |
2149 | C<struct sigaction>. This object will be destroyed automatically when |
2150 | it is no longer needed. The first parameter is the handler, a sub | |
2151 | reference. The second parameter is a C<POSIX::SigSet> object, it | |
2152 | defaults to the empty set. The third parameter contains the | |
28757baa | 2153 | C<sa_flags>, it defaults to 0. |
cb1a09d0 | 2154 | |
28757baa | 2155 | $sigset = POSIX::SigSet->new(SIGINT, SIGQUIT); |
b70c169c FC |
2156 | $sigaction = POSIX::SigAction->new( |
2157 | \&handler, $sigset, &POSIX::SA_NOCLDSTOP | |
2158 | ); | |
cb1a09d0 | 2159 | |
d36b6582 | 2160 | This C<POSIX::SigAction> object is intended for use with the C<POSIX::sigaction()> |
cb1a09d0 | 2161 | function. |
37120919 AD |
2162 | |
2163 | =back | |
2164 | ||
557c0de7 BD |
2165 | =over 8 |
2166 | ||
41cd218c | 2167 | =item C<handler> |
557c0de7 | 2168 | |
41cd218c | 2169 | =item C<mask> |
557c0de7 | 2170 | |
41cd218c | 2171 | =item C<flags> |
557c0de7 BD |
2172 | |
2173 | accessor functions to get/set the values of a SigAction object. | |
2174 | ||
2175 | $sigset = $sigaction->mask; | |
2176 | $sigaction->flags(&POSIX::SA_RESTART); | |
2177 | ||
41cd218c | 2178 | =item C<safe> |
d36b6582 CS |
2179 | |
2180 | accessor function for the "safe signals" flag of a SigAction object; see | |
2181 | L<perlipc> for general information on safe (a.k.a. "deferred") signals. If | |
2182 | you wish to handle a signal safely, use this accessor to set the "safe" flag | |
2183 | in the C<POSIX::SigAction> object: | |
2184 | ||
2185 | $sigaction->safe(1); | |
2186 | ||
2187 | You may also examine the "safe" flag on the output action object which is | |
2188 | filled in when given as the third parameter to C<POSIX::sigaction()>: | |
2189 | ||
2190 | sigaction(SIGINT, $new_action, $old_action); | |
2191 | if ($old_action->safe) { | |
2192 | # previous SIGINT handler used safe signals | |
2193 | } | |
2194 | ||
557c0de7 BD |
2195 | =back |
2196 | ||
41cd218c | 2197 | =head2 C<POSIX::SigRt> |
3609ea0d JH |
2198 | |
2199 | =over 8 | |
2200 | ||
41cd218c | 2201 | =item C<%SIGRT> |
3609ea0d JH |
2202 | |
2203 | A hash of the POSIX realtime signal handlers. It is an extension of | |
41cd218c KW |
2204 | the standard C<%SIG>, the C<$POSIX::SIGRT{SIGRTMIN}> is roughly equivalent |
2205 | to C<$SIG{SIGRTMIN}>, but the right POSIX moves (see below) are made with | |
2206 | the C<POSIX::SigSet> and C<POSIX::sigaction> instead of accessing the C<%SIG>. | |
3609ea0d | 2207 | |
41cd218c | 2208 | You can set the C<%POSIX::SIGRT> elements to set the POSIX realtime |
3609ea0d JH |
2209 | signal handlers, use C<delete> and C<exists> on the elements, and use |
2210 | C<scalar> on the C<%POSIX::SIGRT> to find out how many POSIX realtime | |
41cd218c | 2211 | signals there are available S<C<(SIGRTMAX - SIGRTMIN + 1>>, the C<SIGRTMAX> is |
3609ea0d JH |
2212 | a valid POSIX realtime signal). |
2213 | ||
41cd218c | 2214 | Setting the C<%SIGRT> elements is equivalent to calling this: |
3609ea0d JH |
2215 | |
2216 | sub new { | |
2217 | my ($rtsig, $handler, $flags) = @_; | |
b8921b3e | 2218 | my $sigset = POSIX::SigSet($rtsig); |
b70c169c | 2219 | my $sigact = POSIX::SigAction->new($handler,$sigset,$flags); |
3609ea0d JH |
2220 | sigaction($rtsig, $sigact); |
2221 | } | |
2222 | ||
2223 | The flags default to zero, if you want something different you can | |
41cd218c | 2224 | either use C<local> on C<$POSIX::SigRt::SIGACTION_FLAGS>, or you can |
3609ea0d | 2225 | derive from POSIX::SigRt and define your own C<new()> (the tied hash |
41cd218c KW |
2226 | STORE method of the C<%SIGRT> calls C<new($rtsig, $handler, $SIGACTION_FLAGS)>, |
2227 | where the C<$rtsig> ranges from zero to S<C<SIGRTMAX - SIGRTMIN + 1)>>. | |
3609ea0d | 2228 | |
41cd218c | 2229 | Just as with any signal, you can use C<sigaction($rtsig, undef, $oa)> to |
3609ea0d JH |
2230 | retrieve the installed signal handler (or, rather, the signal action). |
2231 | ||
2232 | B<NOTE:> whether POSIX realtime signals really work in your system, or | |
2233 | whether Perl has been compiled so that it works with them, is outside | |
2234 | of this discussion. | |
2235 | ||
41cd218c | 2236 | =item C<SIGRTMIN> |
3609ea0d JH |
2237 | |
2238 | Return the minimum POSIX realtime signal number available, or C<undef> | |
2239 | if no POSIX realtime signals are available. | |
2240 | ||
41cd218c | 2241 | =item C<SIGRTMAX> |
3609ea0d JH |
2242 | |
2243 | Return the maximum POSIX realtime signal number available, or C<undef> | |
2244 | if no POSIX realtime signals are available. | |
2245 | ||
2246 | =back | |
2247 | ||
41cd218c | 2248 | =head2 C<POSIX::SigSet> |
37120919 AD |
2249 | |
2250 | =over 8 | |
2251 | ||
41cd218c | 2252 | =item C<new> |
37120919 AD |
2253 | |
2254 | Create a new SigSet object. This object will be destroyed automatically | |
2255 | when it is no longer needed. Arguments may be supplied to initialize the | |
2256 | set. | |
2257 | ||
2258 | Create an empty set. | |
2259 | ||
2260 | $sigset = POSIX::SigSet->new; | |
2261 | ||
41cd218c | 2262 | Create a set with C<SIGUSR1>. |
37120919 AD |
2263 | |
2264 | $sigset = POSIX::SigSet->new( &POSIX::SIGUSR1 ); | |
2265 | ||
41cd218c | 2266 | =item C<addset> |
37120919 AD |
2267 | |
2268 | Add a signal to a SigSet object. | |
2269 | ||
2270 | $sigset->addset( &POSIX::SIGUSR2 ); | |
2271 | ||
2272 | Returns C<undef> on failure. | |
2273 | ||
41cd218c | 2274 | =item C<delset> |
37120919 AD |
2275 | |
2276 | Remove a signal from the SigSet object. | |
2277 | ||
2278 | $sigset->delset( &POSIX::SIGUSR2 ); | |
2279 | ||
2280 | Returns C<undef> on failure. | |
2281 | ||
41cd218c | 2282 | =item C<emptyset> |
37120919 AD |
2283 | |
2284 | Initialize the SigSet object to be empty. | |
2285 | ||
2286 | $sigset->emptyset(); | |
2287 | ||
2288 | Returns C<undef> on failure. | |
2289 | ||
41cd218c | 2290 | =item C<fillset> |
37120919 AD |
2291 | |
2292 | Initialize the SigSet object to include all signals. | |
2293 | ||
2294 | $sigset->fillset(); | |
2295 | ||
2296 | Returns C<undef> on failure. | |
2297 | ||
41cd218c | 2298 | =item C<ismember> |
37120919 AD |
2299 | |
2300 | Tests the SigSet object to see if it contains a specific signal. | |
2301 | ||
2302 | if( $sigset->ismember( &POSIX::SIGUSR1 ) ){ | |
2303 | print "contains SIGUSR1\n"; | |
2304 | } | |
2305 | ||
2306 | =back | |
2307 | ||
41cd218c | 2308 | =head2 C<POSIX::Termios> |
37120919 AD |
2309 | |
2310 | =over 8 | |
2311 | ||
41cd218c | 2312 | =item C<new> |
37120919 AD |
2313 | |
2314 | Create a new Termios object. This object will be destroyed automatically | |
4d0de388 | 2315 | when it is no longer needed. A Termios object corresponds to the C<termios> |
41cd218c KW |
2316 | C struct. C<new()> mallocs a new one, C<getattr()> fills it from a file descriptor, |
2317 | and C<setattr()> sets a file descriptor's parameters to match Termios' contents. | |
37120919 AD |
2318 | |
2319 | $termios = POSIX::Termios->new; | |
2320 | ||
41cd218c | 2321 | =item C<getattr> |
37120919 | 2322 | |
cb1a09d0 AD |
2323 | Get terminal control attributes. |
2324 | ||
4d0de388 | 2325 | Obtain the attributes for C<stdin>. |
cb1a09d0 | 2326 | |
220f811a | 2327 | $termios->getattr( 0 ) # Recommended for clarity. |
cb1a09d0 AD |
2328 | $termios->getattr() |
2329 | ||
2330 | Obtain the attributes for stdout. | |
2331 | ||
2332 | $termios->getattr( 1 ) | |
37120919 AD |
2333 | |
2334 | Returns C<undef> on failure. | |
2335 | ||
41cd218c | 2336 | =item C<getcc> |
37120919 | 2337 | |
4d0de388 | 2338 | Retrieve a value from the C<c_cc> field of a C<termios> object. The C<c_cc> field is |
37120919 AD |
2339 | an array so an index must be specified. |
2340 | ||
2341 | $c_cc[1] = $termios->getcc(1); | |
2342 | ||
41cd218c | 2343 | =item C<getcflag> |
37120919 | 2344 | |
4d0de388 | 2345 | Retrieve the C<c_cflag> field of a C<termios> object. |
37120919 AD |
2346 | |
2347 | $c_cflag = $termios->getcflag; | |
2348 | ||
41cd218c | 2349 | =item C<getiflag> |
37120919 | 2350 | |
4d0de388 | 2351 | Retrieve the C<c_iflag> field of a C<termios> object. |
37120919 AD |
2352 | |
2353 | $c_iflag = $termios->getiflag; | |
2354 | ||
41cd218c | 2355 | =item C<getispeed> |
37120919 AD |
2356 | |
2357 | Retrieve the input baud rate. | |
2358 | ||
2359 | $ispeed = $termios->getispeed; | |
2360 | ||
41cd218c | 2361 | =item C<getlflag> |
37120919 | 2362 | |
4d0de388 | 2363 | Retrieve the C<c_lflag> field of a C<termios> object. |
37120919 AD |
2364 | |
2365 | $c_lflag = $termios->getlflag; | |
2366 | ||
41cd218c | 2367 | =item C<getoflag> |
37120919 | 2368 | |
4d0de388 | 2369 | Retrieve the C<c_oflag> field of a C<termios> object. |
37120919 AD |
2370 | |
2371 | $c_oflag = $termios->getoflag; | |
2372 | ||
41cd218c | 2373 | =item C<getospeed> |
37120919 AD |
2374 | |
2375 | Retrieve the output baud rate. | |
2376 | ||
2377 | $ospeed = $termios->getospeed; | |
2378 | ||
41cd218c | 2379 | =item C<setattr> |
37120919 | 2380 | |
cb1a09d0 AD |
2381 | Set terminal control attributes. |
2382 | ||
2383 | Set attributes immediately for stdout. | |
2384 | ||
2385 | $termios->setattr( 1, &POSIX::TCSANOW ); | |
37120919 AD |
2386 | |
2387 | Returns C<undef> on failure. | |
2388 | ||
41cd218c | 2389 | =item C<setcc> |
37120919 | 2390 | |
4d0de388 | 2391 | Set a value in the C<c_cc> field of a C<termios> object. The C<c_cc> field is an |
37120919 AD |
2392 | array so an index must be specified. |
2393 | ||
6b7a6f50 | 2394 | $termios->setcc( &POSIX::VEOF, 1 ); |
37120919 | 2395 | |
41cd218c | 2396 | =item C<setcflag> |
37120919 | 2397 | |
4d0de388 | 2398 | Set the C<c_cflag> field of a C<termios> object. |
37120919 | 2399 | |
55d729e4 | 2400 | $termios->setcflag( $c_cflag | &POSIX::CLOCAL ); |
37120919 | 2401 | |
41cd218c | 2402 | =item C<setiflag> |
37120919 | 2403 | |
4d0de388 | 2404 | Set the C<c_iflag> field of a C<termios> object. |
37120919 | 2405 | |
55d729e4 | 2406 | $termios->setiflag( $c_iflag | &POSIX::BRKINT ); |
37120919 | 2407 | |
41cd218c | 2408 | =item C<setispeed> |
37120919 AD |
2409 | |
2410 | Set the input baud rate. | |
2411 | ||
2412 | $termios->setispeed( &POSIX::B9600 ); | |
2413 | ||
2414 | Returns C<undef> on failure. | |
2415 | ||
41cd218c | 2416 | =item C<setlflag> |
37120919 | 2417 | |
4d0de388 | 2418 | Set the C<c_lflag> field of a C<termios> object. |
37120919 | 2419 | |
55d729e4 | 2420 | $termios->setlflag( $c_lflag | &POSIX::ECHO ); |
37120919 | 2421 | |
41cd218c | 2422 | =item C<setoflag> |
37120919 | 2423 | |
4d0de388 | 2424 | Set the C<c_oflag> field of a C<termios> object. |
37120919 | 2425 | |
55d729e4 | 2426 | $termios->setoflag( $c_oflag | &POSIX::OPOST ); |
37120919 | 2427 | |
41cd218c | 2428 | =item C<setospeed> |
37120919 AD |
2429 | |
2430 | Set the output baud rate. | |
2431 | ||
2432 | $termios->setospeed( &POSIX::B9600 ); | |
2433 | ||
2434 | Returns C<undef> on failure. | |
2435 | ||
2436 | =item Baud rate values | |
2437 | ||
41cd218c | 2438 | C<B38400> C<B75> C<B200> C<B134> C<B300> C<B1800> C<B150> C<B0> C<B19200> C<B1200> C<B9600> C<B600> C<B4800> C<B50> C<B2400> C<B110> |
37120919 AD |
2439 | |
2440 | =item Terminal interface values | |
2441 | ||
41cd218c | 2442 | C<TCSADRAIN> C<TCSANOW> C<TCOON> C<TCIOFLUSH> C<TCOFLUSH> C<TCION> C<TCIFLUSH> C<TCSAFLUSH> C<TCIOFF> C<TCOOFF> |
37120919 | 2443 | |
41cd218c | 2444 | =item C<c_cc> field values |
37120919 | 2445 | |
41cd218c | 2446 | C<VEOF> C<VEOL> C<VERASE> C<VINTR> C<VKILL> C<VQUIT> C<VSUSP> C<VSTART> C<VSTOP> C<VMIN> C<VTIME> C<NCCS> |
37120919 | 2447 | |
41cd218c | 2448 | =item C<c_cflag> field values |
37120919 | 2449 | |
41cd218c | 2450 | C<CLOCAL> C<CREAD> C<CSIZE> C<CS5> C<CS6> C<CS7> C<CS8> C<CSTOPB> C<HUPCL> C<PARENB> C<PARODD> |
37120919 | 2451 | |
41cd218c | 2452 | =item C<c_iflag> field values |
37120919 | 2453 | |
41cd218c | 2454 | C<BRKINT> C<ICRNL> C<IGNBRK> C<IGNCR> C<IGNPAR> C<INLCR> C<INPCK> C<ISTRIP> C<IXOFF> C<IXON> C<PARMRK> |
37120919 | 2455 | |
41cd218c | 2456 | =item C<c_lflag> field values |
37120919 | 2457 | |
41cd218c | 2458 | C<ECHO> C<ECHOE> C<ECHOK> C<ECHONL> C<ICANON> C<IEXTEN> C<ISIG> C<NOFLSH> C<TOSTOP> |
37120919 | 2459 | |
41cd218c | 2460 | =item C<c_oflag> field values |
37120919 | 2461 | |
41cd218c | 2462 | C<OPOST> |
37120919 AD |
2463 | |
2464 | =back | |
2465 | ||
2466 | =head1 PATHNAME CONSTANTS | |
2467 | ||
2468 | =over 8 | |
2469 | ||
2470 | =item Constants | |
2471 | ||
41cd218c KW |
2472 | C<_PC_CHOWN_RESTRICTED> C<_PC_LINK_MAX> C<_PC_MAX_CANON> C<_PC_MAX_INPUT> C<_PC_NAME_MAX> |
2473 | C<_PC_NO_TRUNC> C<_PC_PATH_MAX> C<_PC_PIPE_BUF> C<_PC_VDISABLE> | |
37120919 AD |
2474 | |
2475 | =back | |
2476 | ||
2477 | =head1 POSIX CONSTANTS | |
2478 | ||
2479 | =over 8 | |
2480 | ||
2481 | =item Constants | |
2482 | ||
41cd218c KW |
2483 | C<_POSIX_ARG_MAX> C<_POSIX_CHILD_MAX> C<_POSIX_CHOWN_RESTRICTED> C<_POSIX_JOB_CONTROL> |
2484 | C<_POSIX_LINK_MAX> C<_POSIX_MAX_CANON> C<_POSIX_MAX_INPUT> C<_POSIX_NAME_MAX> | |
2485 | C<_POSIX_NGROUPS_MAX> C<_POSIX_NO_TRUNC> C<_POSIX_OPEN_MAX> C<_POSIX_PATH_MAX> | |
2486 | C<_POSIX_PIPE_BUF> C<_POSIX_SAVED_IDS> C<_POSIX_SSIZE_MAX> C<_POSIX_STREAM_MAX> | |
2487 | C<_POSIX_TZNAME_MAX> C<_POSIX_VDISABLE> C<_POSIX_VERSION> | |
37120919 AD |
2488 | |
2489 | =back | |
2490 | ||
4fd667a8 TC |
2491 | =head1 RESOURCE CONSTANTS |
2492 | ||
2493 | Imported with the C<:sys_resource_h> tag. | |
2494 | ||
2495 | =over 8 | |
2496 | ||
2497 | =item Constants | |
2498 | ||
2499 | C<PRIO_PROCESS> C<PRIO_PGRP> C<PRIO_USER> | |
2500 | ||
2501 | =back | |
2502 | ||
37120919 AD |
2503 | =head1 SYSTEM CONFIGURATION |
2504 | ||
2505 | =over 8 | |
2506 | ||
2507 | =item Constants | |
2508 | ||
41cd218c KW |
2509 | C<_SC_ARG_MAX> C<_SC_CHILD_MAX> C<_SC_CLK_TCK> C<_SC_JOB_CONTROL> C<_SC_NGROUPS_MAX> |
2510 | C<_SC_OPEN_MAX> C<_SC_PAGESIZE> C<_SC_SAVED_IDS> C<_SC_STREAM_MAX> C<_SC_TZNAME_MAX> | |
2511 | C<_SC_VERSION> | |
37120919 AD |
2512 | |
2513 | =back | |
2514 | ||
2515 | =head1 ERRNO | |
2516 | ||
2517 | =over 8 | |
2518 | ||
2519 | =item Constants | |
2520 | ||
41cd218c KW |
2521 | C<E2BIG> C<EACCES> C<EADDRINUSE> C<EADDRNOTAVAIL> C<EAFNOSUPPORT> C<EAGAIN> C<EALREADY> C<EBADF> C<EBADMSG> |
2522 | C<EBUSY> C<ECANCELED> C<ECHILD> C<ECONNABORTED> C<ECONNREFUSED> C<ECONNRESET> C<EDEADLK> C<EDESTADDRREQ> | |
2523 | C<EDOM> C<EDQUOT> C<EEXIST> C<EFAULT> C<EFBIG> C<EHOSTDOWN> C<EHOSTUNREACH> C<EIDRM> C<EILSEQ> C<EINPROGRESS> | |
2524 | C<EINTR> C<EINVAL> C<EIO> C<EISCONN> C<EISDIR> C<ELOOP> C<EMFILE> C<EMLINK> C<EMSGSIZE> C<ENAMETOOLONG> | |
2525 | C<ENETDOWN> C<ENETRESET> C<ENETUNREACH> C<ENFILE> C<ENOBUFS> C<ENODATA> C<ENODEV> C<ENOENT> C<ENOEXEC> | |
2526 | C<ENOLCK> C<ENOLINK> C<ENOMEM> C<ENOMSG> C<ENOPROTOOPT> C<ENOSPC> C<ENOSR> C<ENOSTR> C<ENOSYS> C<ENOTBLK> | |
2527 | C<ENOTCONN> C<ENOTDIR> C<ENOTEMPTY> C<ENOTRECOVERABLE> C<ENOTSOCK> C<ENOTSUP> C<ENOTTY> C<ENXIO> | |
2528 | C<EOPNOTSUPP> C<EOTHER> C<EOVERFLOW> C<EOWNERDEAD> C<EPERM> C<EPFNOSUPPORT> C<EPIPE> C<EPROCLIM> C<EPROTO> | |
2529 | C<EPROTONOSUPPORT> C<EPROTOTYPE> C<ERANGE> C<EREMOTE> C<ERESTART> C<EROFS> C<ESHUTDOWN> | |
2530 | C<ESOCKTNOSUPPORT> C<ESPIPE> C<ESRCH> C<ESTALE> C<ETIME> C<ETIMEDOUT> C<ETOOMANYREFS> C<ETXTBSY> C<EUSERS> | |
2531 | C<EWOULDBLOCK> C<EXDEV> | |
37120919 AD |
2532 | |
2533 | =back | |
2534 | ||
2535 | =head1 FCNTL | |
2536 | ||
2537 | =over 8 | |
2538 | ||
2539 | =item Constants | |
2540 | ||
41cd218c KW |
2541 | C<FD_CLOEXEC> C<F_DUPFD> C<F_GETFD> C<F_GETFL> C<F_GETLK> C<F_OK> C<F_RDLCK> C<F_SETFD> C<F_SETFL> C<F_SETLK> |
2542 | C<F_SETLKW> C<F_UNLCK> C<F_WRLCK> C<O_ACCMODE> C<O_APPEND> C<O_CREAT> C<O_EXCL> C<O_NOCTTY> C<O_NONBLOCK> | |
2543 | C<O_RDONLY> C<O_RDWR> C<O_TRUNC> C<O_WRONLY> | |
37120919 AD |
2544 | |
2545 | =back | |
2546 | ||
2547 | =head1 FLOAT | |
2548 | ||
2549 | =over 8 | |
2550 | ||
2551 | =item Constants | |
2552 | ||
41cd218c KW |
2553 | C<DBL_DIG> C<DBL_EPSILON> C<DBL_MANT_DIG> C<DBL_MAX> C<DBL_MAX_10_EXP> C<DBL_MAX_EXP> C<DBL_MIN> |
2554 | C<DBL_MIN_10_EXP> C<DBL_MIN_EXP> C<FLT_DIG> C<FLT_EPSILON> C<FLT_MANT_DIG> C<FLT_MAX> | |
2555 | C<FLT_MAX_10_EXP> C<FLT_MAX_EXP> C<FLT_MIN> C<FLT_MIN_10_EXP> C<FLT_MIN_EXP> C<FLT_RADIX> | |
2556 | C<FLT_ROUNDS> C<LDBL_DIG> C<LDBL_EPSILON> C<LDBL_MANT_DIG> C<LDBL_MAX> C<LDBL_MAX_10_EXP> | |
2557 | C<LDBL_MAX_EXP> C<LDBL_MIN> C<LDBL_MIN_10_EXP> C<LDBL_MIN_EXP> | |
37120919 AD |
2558 | |
2559 | =back | |
2560 | ||
98ab3abf AP |
2561 | =head1 FLOATING-POINT ENVIRONMENT |
2562 | ||
2563 | =over 8 | |
2564 | ||
2565 | =item Constants | |
2566 | ||
2567 | C<FE_DOWNWARD> C<FE_TONEAREST> C<FE_TOWARDZERO> C<FE_UPWARD> | |
2568 | on systems that support them. | |
2569 | ||
2570 | =back | |
2571 | ||
37120919 AD |
2572 | =head1 LIMITS |
2573 | ||
2574 | =over 8 | |
2575 | ||
2576 | =item Constants | |
2577 | ||
41cd218c KW |
2578 | C<ARG_MAX> C<CHAR_BIT> C<CHAR_MAX> C<CHAR_MIN> C<CHILD_MAX> C<INT_MAX> C<INT_MIN> C<LINK_MAX> C<LONG_MAX> |
2579 | C<LONG_MIN> C<MAX_CANON> C<MAX_INPUT> C<MB_LEN_MAX> C<NAME_MAX> C<NGROUPS_MAX> C<OPEN_MAX> C<PATH_MAX> | |
2580 | C<PIPE_BUF> C<SCHAR_MAX> C<SCHAR_MIN> C<SHRT_MAX> C<SHRT_MIN> C<SSIZE_MAX> C<STREAM_MAX> C<TZNAME_MAX> | |
2581 | C<UCHAR_MAX> C<UINT_MAX> C<ULONG_MAX> C<USHRT_MAX> | |
37120919 AD |
2582 | |
2583 | =back | |
2584 | ||
2585 | =head1 LOCALE | |
2586 | ||
2587 | =over 8 | |
2588 | ||
2589 | =item Constants | |
2590 | ||
4d0de388 KW |
2591 | C<LC_ALL> C<LC_COLLATE> C<LC_CTYPE> C<LC_MONETARY> C<LC_NUMERIC> C<LC_TIME> C<LC_MESSAGES> |
2592 | on systems that support them. | |
37120919 AD |
2593 | |
2594 | =back | |
2595 | ||
2596 | =head1 MATH | |
2597 | ||
2598 | =over 8 | |
2599 | ||
2600 | =item Constants | |
2601 | ||
41cd218c | 2602 | C<HUGE_VAL> |
37120919 | 2603 | |
98ab3abf AP |
2604 | C<FP_ILOGB0> C<FP_ILOGBNAN> C<FP_INFINITE> C<FP_NAN> C<FP_NORMAL> C<FP_SUBNORMAL> C<FP_ZERO> |
2605 | C<INFINITY> C<NAN> C<Inf> C<NaN> | |
2606 | C<M_1_PI> C<M_2_PI> C<M_2_SQRTPI> C<M_E> C<M_LN10> C<M_LN2> C<M_LOG10E> C<M_LOG2E> C<M_PI> | |
2607 | C<M_PI_2> C<M_PI_4> C<M_SQRT1_2> C<M_SQRT2> | |
2608 | on systems with C99 support. | |
2609 | ||
37120919 AD |
2610 | =back |
2611 | ||
2612 | =head1 SIGNAL | |
2613 | ||
2614 | =over 8 | |
2615 | ||
2616 | =item Constants | |
2617 | ||
41cd218c KW |
2618 | C<SA_NOCLDSTOP> C<SA_NOCLDWAIT> C<SA_NODEFER> C<SA_ONSTACK> C<SA_RESETHAND> C<SA_RESTART> |
2619 | C<SA_SIGINFO> C<SIGABRT> C<SIGALRM> C<SIGCHLD> C<SIGCONT> C<SIGFPE> C<SIGHUP> C<SIGILL> C<SIGINT> | |
2620 | C<SIGKILL> C<SIGPIPE> C<SIGQUIT> C<SIGSEGV> C<SIGSTOP> C<SIGTERM> C<SIGTSTP> C<SIGTTIN> C<SIGTTOU> | |
2621 | C<SIGUSR1> C<SIGUSR2> C<SIG_BLOCK> C<SIG_DFL> C<SIG_ERR> C<SIG_IGN> C<SIG_SETMASK> | |
2622 | C<SIG_UNBLOCK> | |
34e79b75 DIM |
2623 | C<ILL_ILLOPC> C<ILL_ILLOPN> C<ILL_ILLADR> C<ILL_ILLTRP> C<ILL_PRVOPC> C<ILL_PRVREG> C<ILL_COPROC> |
2624 | C<ILL_BADSTK> C<FPE_INTDIV> C<FPE_INTOVF> C<FPE_FLTDIV> C<FPE_FLTOVF> C<FPE_FLTUND> C<FPE_FLTRES> | |
2625 | C<FPE_FLTINV> C<FPE_FLTSUB> C<SEGV_MAPERR> C<SEGV_ACCERR> C<BUS_ADRALN> C<BUS_ADRERR> | |
2626 | C<BUS_OBJERR> C<TRAP_BRKPT> C<TRAP_TRACE> C<CLD_EXITED> C<CLD_KILLED> C<CLD_DUMPED> C<CLD_TRAPPED> | |
2627 | C<CLD_STOPPED> C<CLD_CONTINUED> C<POLL_IN> C<POLL_OUT> C<POLL_MSG> C<POLL_ERR> C<POLL_PRI> | |
2628 | C<POLL_HUP> C<SI_USER> C<SI_QUEUE> C<SI_TIMER> C<SI_ASYNCIO> C<SI_MESGQ> | |
37120919 AD |
2629 | |
2630 | =back | |
2631 | ||
2632 | =head1 STAT | |
2633 | ||
2634 | =over 8 | |
2635 | ||
2636 | =item Constants | |
2637 | ||
41cd218c KW |
2638 | C<S_IRGRP> C<S_IROTH> C<S_IRUSR> C<S_IRWXG> C<S_IRWXO> C<S_IRWXU> C<S_ISGID> C<S_ISUID> C<S_IWGRP> C<S_IWOTH> |
2639 | C<S_IWUSR> C<S_IXGRP> C<S_IXOTH> C<S_IXUSR> | |
37120919 AD |
2640 | |
2641 | =item Macros | |
2642 | ||
41cd218c | 2643 | C<S_ISBLK> C<S_ISCHR> C<S_ISDIR> C<S_ISFIFO> C<S_ISREG> |
37120919 AD |
2644 | |
2645 | =back | |
2646 | ||
2647 | =head1 STDLIB | |
2648 | ||
2649 | =over 8 | |
2650 | ||
2651 | =item Constants | |
2652 | ||
41cd218c | 2653 | C<EXIT_FAILURE> C<EXIT_SUCCESS> C<MB_CUR_MAX> C<RAND_MAX> |
37120919 AD |
2654 | |
2655 | =back | |
2656 | ||
2657 | =head1 STDIO | |
2658 | ||
2659 | =over 8 | |
2660 | ||
2661 | =item Constants | |
2662 | ||
1cb852db | 2663 | C<BUFSIZ> C<EOF> C<FILENAME_MAX> C<L_ctermid> C<L_cuserid> C<TMP_MAX> |
37120919 AD |
2664 | |
2665 | =back | |
2666 | ||
2667 | =head1 TIME | |
2668 | ||
2669 | =over 8 | |
2670 | ||
2671 | =item Constants | |
2672 | ||
41cd218c | 2673 | C<CLK_TCK> C<CLOCKS_PER_SEC> |
37120919 AD |
2674 | |
2675 | =back | |
2676 | ||
2677 | =head1 UNISTD | |
2678 | ||
2679 | =over 8 | |
2680 | ||
2681 | =item Constants | |
2682 | ||
41cd218c | 2683 | C<R_OK> C<SEEK_CUR> C<SEEK_END> C<SEEK_SET> C<STDIN_FILENO> C<STDOUT_FILENO> C<STDERR_FILENO> C<W_OK> C<X_OK> |
37120919 AD |
2684 | |
2685 | =back | |
2686 | ||
2687 | =head1 WAIT | |
2688 | ||
2689 | =over 8 | |
2690 | ||
2691 | =item Constants | |
2692 | ||
41cd218c | 2693 | C<WNOHANG> C<WUNTRACED> |
37120919 | 2694 | |
9d6eb86e JH |
2695 | =over 16 |
2696 | ||
41cd218c | 2697 | =item C<WNOHANG> |
9d6eb86e JH |
2698 | |
2699 | Do not suspend the calling process until a child process | |
2700 | changes state but instead return immediately. | |
2701 | ||
41cd218c | 2702 | =item C<WUNTRACED> |
9d6eb86e JH |
2703 | |
2704 | Catch stopped child processes. | |
2705 | ||
2706 | =back | |
2707 | ||
37120919 AD |
2708 | =item Macros |
2709 | ||
41cd218c | 2710 | C<WIFEXITED> C<WEXITSTATUS> C<WIFSIGNALED> C<WTERMSIG> C<WIFSTOPPED> C<WSTOPSIG> |
37120919 | 2711 | |
9d6eb86e JH |
2712 | =over 16 |
2713 | ||
41cd218c | 2714 | =item C<WIFEXITED> |
9d6eb86e | 2715 | |
41cd218c | 2716 | C<WIFEXITED(${^CHILD_ERROR_NATIVE})> returns true if the child process |
12a72a5a | 2717 | exited normally (C<exit()> or by falling off the end of C<main()>) |
9d6eb86e | 2718 | |
41cd218c | 2719 | =item C<WEXITSTATUS> |
9d6eb86e | 2720 | |
41cd218c KW |
2721 | C<WEXITSTATUS(${^CHILD_ERROR_NATIVE})> returns the normal exit status of |
2722 | the child process (only meaningful if C<WIFEXITED(${^CHILD_ERROR_NATIVE})> | |
12a72a5a | 2723 | is true) |
9d6eb86e | 2724 | |
41cd218c | 2725 | =item C<WIFSIGNALED> |
9d6eb86e | 2726 | |
41cd218c | 2727 | C<WIFSIGNALED(${^CHILD_ERROR_NATIVE})> returns true if the child process |
12a72a5a | 2728 | terminated because of a signal |
9d6eb86e | 2729 | |
41cd218c | 2730 | =item C<WTERMSIG> |
9d6eb86e | 2731 | |
41cd218c KW |
2732 | C<WTERMSIG(${^CHILD_ERROR_NATIVE})> returns the signal the child process |
2733 | terminated for (only meaningful if | |
2734 | C<WIFSIGNALED(${^CHILD_ERROR_NATIVE})> | |
12a72a5a | 2735 | is true) |
9d6eb86e | 2736 | |
41cd218c | 2737 | =item C<WIFSTOPPED> |
9d6eb86e | 2738 | |
41cd218c | 2739 | C<WIFSTOPPED(${^CHILD_ERROR_NATIVE})> returns true if the child process is |
12a72a5a | 2740 | currently stopped (can happen only if you specified the WUNTRACED flag |
41cd218c | 2741 | to C<waitpid()>) |
9d6eb86e | 2742 | |
41cd218c | 2743 | =item C<WSTOPSIG> |
9d6eb86e | 2744 | |
41cd218c KW |
2745 | C<WSTOPSIG(${^CHILD_ERROR_NATIVE})> returns the signal the child process |
2746 | was stopped for (only meaningful if | |
2747 | C<WIFSTOPPED(${^CHILD_ERROR_NATIVE})> | |
12a72a5a | 2748 | is true) |
9d6eb86e JH |
2749 | |
2750 | =back | |
2751 | ||
37120919 AD |
2752 | =back |
2753 | ||
a28fff51 SH |
2754 | =head1 WINSOCK |
2755 | ||
2756 | (Windows only.) | |
2757 | ||
2758 | =over 8 | |
2759 | ||
2760 | =item Constants | |
2761 | ||
2762 | C<WSAEINTR> C<WSAEBADF> C<WSAEACCES> C<WSAEFAULT> C<WSAEINVAL> C<WSAEMFILE> C<WSAEWOULDBLOCK> | |
2763 | C<WSAEINPROGRESS> C<WSAEALREADY> C<WSAENOTSOCK> C<WSAEDESTADDRREQ> C<WSAEMSGSIZE> | |
2764 | C<WSAEPROTOTYPE> C<WSAENOPROTOOPT> C<WSAEPROTONOSUPPORT> C<WSAESOCKTNOSUPPORT> | |
2765 | C<WSAEOPNOTSUPP> C<WSAEPFNOSUPPORT> C<WSAEAFNOSUPPORT> C<WSAEADDRINUSE> | |
2766 | C<WSAEADDRNOTAVAIL> C<WSAENETDOWN> C<WSAENETUNREACH> C<WSAENETRESET> C<WSAECONNABORTED> | |
2767 | C<WSAECONNRESET> C<WSAENOBUFS> C<WSAEISCONN> C<WSAENOTCONN> C<WSAESHUTDOWN> | |
2768 | C<WSAETOOMANYREFS> C<WSAETIMEDOUT> C<WSAECONNREFUSED> C<WSAELOOP> C<WSAENAMETOOLONG> | |
2769 | C<WSAEHOSTDOWN> C<WSAEHOSTUNREACH> C<WSAENOTEMPTY> C<WSAEPROCLIM> C<WSAEUSERS> | |
2770 | C<WSAEDQUOT> C<WSAESTALE> C<WSAEREMOTE> C<WSAEDISCON> C<WSAENOMORE> C<WSAECANCELLED> | |
2771 | C<WSAEINVALIDPROCTABLE> C<WSAEINVALIDPROVIDER> C<WSAEPROVIDERFAILEDINIT> | |
2772 | C<WSAEREFUSED> | |
2773 | ||
2774 | =back | |
2775 |