1POSIX::2008(3)        User Contributed Perl Documentation       POSIX::2008(3)
2
3
4

NAME

6       POSIX::2008 - Perl interface to POSIX.1-2008
7

SYNOPSIS

9         use POSIX::2008 qw(:fcntl openat pwrite);
10
11         sysopen my $dh, '/tmp', O_RDONLY|O_DIRECTORY|O_NOFOLLOW or die 'Dafuq?';
12         my $fh = openat($dh, 'foobar', O_RDWR|O_CREAT);
13         pwrite($fh, 'fuckyounsa', 10, 0);
14

DESCRIPTION

16       POSIX::2008 contains many of the interfaces specified by POSIX.1-2008
17       <https://pubs.opengroup.org/onlinepubs/9699919799/> that the core POSIX
18       module withholds, implements in Perl or fucked up.
19
20       It also contains a few nonstandard interfaces present in Linux, BSD and
21       Solaris that are extensions of the POSIX interfaces.
22
23       This module is provided "as is" unless someone volunteers to maintain
24       it.
25

FILE DESCRIPTORS AND HANDLES

27       Since version 0.05, all I/O functions that take numeric file
28       descriptors also accept Perl file or directory handles.
29

SYSTEM CALL RETURN VALUES

31       A system call return value of -1 meaning "error" is mapped to undef.
32
33       A system call return value of 0 meaning "success" is mapped to "0 but
34       true".
35
36       For system calls where 0 does not just mean "success", 0 is returned
37       unchanged. These are open(), read(), write(), readv(), writev(),
38       pread(), pwrite(), preadv(), pwritev(), preadv2(), pwritev2(),
39       getpriority().  openat() gets a special treatment in this regard, see
40       below.
41

FUNCTIONS

43       "a64l"
44           l = a64l(s);
45
46       "abort"
47           abort();
48
49       "abs"
50           ui = abs(i);
51
52           Calls llabs(), labs(), or abs(), whichever is the maximum supported
53           by your system.
54
55           Note that the library functions use signed integers, so abs(~0) is
56           1.  If you don't want that, use CORE::abs().
57
58       "access"
59           ret = access(path, mode);
60
61       "acos"
62           y = acos(x);
63
64       "acosh"
65           y = acosh(x);
66
67       "alarm"
68           remaining_sec = alarm(sec);
69
70       "asin"
71           y = asin(x);
72
73       "asinh"
74           y = asinh(x);
75
76       "atan2"
77           z = atan2(y, x);
78
79       "atan"
80           y = atan(x);
81
82       "atanh"
83           y = atanh(x);
84
85       "atof"
86           f = atof(s);
87
88       "atoi"
89           i = atoi(s);
90
91           Calls atoll(), atol(), or atoi(), whichever is the maximum
92           supported by your system. This is of course silly because you could
93           just use int().
94
95       "basename"
96           s = basename(path);
97
98       "cabs"
99           r = cabs(re, im);
100
101       "cacos"
102           (re, im) = cacos(re, im);
103
104       "cacosh"
105           (re, im) = cacosh(re, im);
106
107       "carg"
108           phi = carg(re, im);
109
110       "casinh"
111           (re, im) = casinh(re, im);
112
113       "catan"
114           (re, im) = catan(re, im);
115
116       "catanh"
117           (re, im) = catanh(re, im);
118
119       "catclose"
120           ret = catclose(catd);
121
122       "catgets"
123           s = catgets(catd, set_id, msg_id, dflt_string);
124
125       "catopen"
126           catd = catopen(name, flag);
127
128       "cbrt"
129           y = cbrt(x);
130
131       "ccos"
132           (re, im) = ccos(re, im);
133
134       "ccosh"
135           (re, im) = ccosh(re, im);
136
137       "ceil"
138           y = ceil(x);
139
140       "cexp"
141           (re, im) = cexp(re, im);
142
143       "chdir"
144           ret = chdir(dir);
145
146           "dir" can be a path, a Perl file handle or a file descriptor.
147
148       "chmod"
149           ret = chmod(what, mode);
150
151           "what" can be a path, a Perl file handle or a file descriptor.
152
153       "chown"
154           ret = chown(what, uid, gid);
155
156           "what" can be a path, a Perl file handle or a file descriptor.
157
158       "cimag"
159           im = cimag(re, im);
160
161       "clock"
162           t = clock()
163
164       "clock_getcpuclockid"
165           clock_id = clock_getcpuclockid(pid);
166
167           pid defaults to $$. Returns undef on error.
168
169       "clock_getres"
170           (sec, nsec) = clock_getres(clock_id);
171
172           clock_id defaults to "CLOCK_REALTIME". Returns empty list on error.
173
174       "clock_gettime"
175           (sec, nsec) = clock_gettime(clock_id);
176
177           clock_id defaults to "CLOCK_REALTIME". Returns empty list on error.
178
179       "clock_nanosleep"
180           (rem_sec, rem_nsec) = clock_nanosleep(clock_id, flags, sec, nsec);
181
182           In scalar context returns the remaining seconds as a floating point
183           number.
184
185       "clock_settime"
186           ret = clock_settime(clock_id, sec, nsec);
187
188       "clog"
189           (re, im) = clog(re, im);
190
191       "close"
192           ret = close(fd);
193
194       "confstr"
195           s = confstr(name);
196
197           name is one of the "_CS_*" integer constants.
198
199       "conj"
200           (re, im) = conj(re, im);
201
202       "copysign"
203           xs = copysign(x, y);
204
205       "cos"
206           y = cos(x);
207
208       "cosh"
209           y = cosh(x);
210
211       "cpow"
212           (re, im) = cpow(re_x, im_x, re_y, im_y);
213
214       "cproj"
215           (re, im) = cproj(re, im);
216
217       "creal"
218           re = creal(re, im);
219
220       "csin"
221           (re, im) = csin(re, im);
222
223       "csinh"
224           (re, im) = csinh(re, im);
225
226       "csqrt"
227           (re, im) = csqrt(re, im);
228
229       "ctan"
230           (re, im) = ctan(re, im);
231
232       "ctanh"
233           (re, im) = ctanh(re, im);
234
235       "dirname"
236           name = dirname(path);
237
238       "div"
239           (quot, rem) = div(numer, denom);
240
241           Calls lldiv(), ldiv(), or div(), whichever is the maximum supported
242           by your system.
243
244           Note that the library functions use signed integers, so "div(~0,
245           1)" is "(-1, 0)". If you don't want that, use Perls int(), "/" and
246           "%".
247
248       "dlclose"
249           dlclose(dlhandle);
250
251       "dlerror"
252           dlerror();
253
254       "dlopen"
255           dlhandle = dlopen(file, mode);
256
257       "dlsym"
258           addr = dlsym(dlhandle, name);
259
260       "drand48"
261           r = drand48();
262
263       "endutxent"
264           endutxent();
265
266       "erand48"
267           (r, X0, X1, X2) = erand48(X0, X1, X2);
268
269       "erf"
270           y = erf(x);
271
272       "erfc"
273           y = erfc(x);
274
275       "exp"
276           y = exp(x);
277
278       "exp2"
279           y = exp2(x);
280
281       "expm1"
282           y = expm1(x);
283
284       "faccessat"
285           ret = faccessat(dirfd, path, amode, flags=0);
286
287           flags is the bitwise OR of zero or more of "AT_EACCESS",
288           "AT_SYMLINK_NOFOLLOW".
289
290       "fchmodat"
291           ret = fchmodat(dirfd, path, mode, flags=0);
292
293           flags can be 0 or "AT_SYMLINK_NOFOLLOW".
294
295       "fchownat"
296           ret = fchownat(dirfd, path, uid, gid, flags=0);
297
298           flags can be 0 or "AT_SYMLINK_NOFOLLOW".
299
300       "fdatasync"
301           ret = fdatasync(fd);
302
303       "fdopen"
304           ret = fdopen(fd, mode);
305
306           Returns a file handle associated with the file descriptor fd or
307           undef on error. mode is one of the values "r", "w", "a" with an
308           optional "+" and/or "b".
309
310           It's similar to IO::Handle::new_from_fd() with the following
311           improvements:
312
313           •   It really calls fdopen(3).
314
315           •   It expects POSIX mode strings (e.g. "r", not "<").
316
317           •   It fails if mode is not compatible with the flags of fd.
318
319       "fdopendir"
320           ret = fdopendir(fd);
321
322           Returns a directory handle associated with the file descriptor fd
323           or undef on error. Usage example:
324
325             my $dh = do {
326               sysopen my $fh, '/tmp', O_RDONLY|O_DIRECTORY|O_NOFOLLOW;
327               fdopendir($fh); # or fdopendir(fileno $fh) but the former also works
328                               # with handles from opendir() for which fileno does
329                               # not work before Perl 5.22
330             };
331             my @files = readdir $dh;  # this would fail with $fh from sysopen
332
333       "fdim"
334           d = fdim(double x, double y);
335
336       "feclearexcept"
337           ret = feclearexcept(excepts);
338
339           Returns "0 but true" on success, undef on error.
340
341       "fegetround"
342           rounding_mode = fegetround();
343
344       "feraiseexcept"
345           ret = feraiseexcept(excepts);
346
347           Returns "0 but true" on success, undef on error.
348
349       "fesetround"
350           ret = fesetround(round);
351
352           Returns "0 but true" on success, undef on error.
353
354       "fetestexcept"
355           excepts_currently_set = fetestexcept(excepts);
356
357       "ffs"
358           pos = ffs(i);
359
360           Calls ffsll(), ffsl(), or ffs(), whichever is the maximum available
361           on your system.
362
363       "floor"
364           y = floor(x);
365
366       "fma"
367           r = fma(x, y, z);
368
369       "fmax"
370           m = fmax(x, y);
371
372       "fmin"
373           m = fmin(x, y);
374
375       "fmod"
376           m = fmod(x, y);
377
378       "fnmatch"
379           ret = fnmatch(pattern, string, flags);
380
381           Returns 0 if string matches pattern, "FNM_NOMATCH" if there is no
382           match, undef if there is an error.
383
384           flags is the bitwise OR of zero or more of "FNM_NOESCAPE",
385           "FNM_PATHNAME", "FNM_PERIOD", "FNM_FILE_NAME", "FNM_LEADING_DIR",
386           "FNM_CASEFOLD".
387
388       "fpclassify"
389           fpclassify(x);
390
391           Returns one of "FP_NAN", "FP_INFINITE", "FP_ZERO", "FP_SUBNORMAL",
392           "FP_NORMAL".
393
394       "fstatat"
395           (dev, ino, mode, nlink, uid, gid, rdev, size, atim_sec, mtim_sec,
396           ctim_sec, blksize, blocks, atim_nsec, mtim_nsec, ctim_nsec) =
397           fstatat(dirfd, path, flags = 0);
398
399           flags is the bitwise OR of zero or more of "AT_SYMLINK_NOFOLLOW",
400           "AT_NO_AUTOMOUNT".
401
402           See stat() for notes on the return values and bugs in CORE::stat().
403
404           Returns an empty list on error.
405
406       "fsync"
407           ret = fsync(fd);
408
409       "futimens"
410           ret = futimens(fd, atime_sec, atime_nsec, mtime_sec, mtime_nsec);
411
412           atime_sec and mtime_sec default to 0, atime_nsec and mtime_nsec
413           default to "UTIME_NOW".
414
415       "getdate"
416           (sec, min, hour, mday, mon, year, wday, yday, isdst) =
417           getdate(string);
418
419       "getdate_err"
420           getdate_err() returns the value of the getdate_err variable.
421
422       "getegid"
423           egid = getegid();
424
425       "geteuid"
426           euid = geteuid();
427
428       "getgid"
429           gid = getgid();
430
431       "gethostid"
432           hostid = gethostid();
433
434       "gethostname"
435           hostname = gethostname();
436
437       "getitimer"
438           (int_sec, int_usec, val_sec, val_usec) = getitimer(which);
439
440           which is one of "ITIMER_REAL", "ITIMER_VIRTUAL", "ITIMER_PROF".
441
442       "getpriority"
443           prio = getpriority(which=PRIO_PROCESS, who=0);
444
445           which can be one of "PRIO_PROCESS", "PRIO_PGRP", "PRIO_USER",
446           defaults to "PRIO_PROCESS". who defaults to 0.
447
448           Returns undef on error.
449
450       "getsid"
451           sid = getsid(pid);
452
453           pid defaults to 0.
454
455       "getuid"
456           uid = getuid();
457
458       "getutxent"
459           (user, id, line, pid, type, sec, usec) = getutxent();
460
461           getutxent() reads a line from the current file position in the utmp
462           file.
463
464       "getutxid"
465           (user, id, line, pid, type, sec, usec) = getutxid(ut_type, ut_id);
466
467           getutxid() searches forward from the current file position in the
468           utmp file based upon ut_type and ut_id. If ut_type is one of
469           "RUN_LVL", "BOOT_TIME", "NEW_TIME", or "OLD_TIME", getutxid() will
470           find the first entry whose ut_type field matches ut_type. If
471           ut_type is one of "INIT_PROCESS", "LOGIN_PROCESS", "USER_PROCESS",
472           or "DEAD_PROCESS", getutxid() will find the first entry whose ut_id
473           field matches ut_id.
474
475       "getutxline"
476           (user, id, line, pid, type, sec, usec) = getutxline(ut_line);
477
478           getutxline() searches forward from the current file position in the
479           utmp file.  It scans entries whose ut_type is "USER_PROCESS" or
480           "LOGIN_PROCESS" and returns the first one whose ut_line field
481           matches ut_line.
482
483       "hypot"
484           r = hypot(x, y);
485
486       "ilogb"
487           y = ilogb(x);
488
489       "isalnum"
490           ret = isalnum(charstring);
491
492           Like POSIX::isalnum() but returns 0 for the empty string.
493
494       "isalpha"
495           ret = isalpha(charstring);
496
497           Like POSIX::isalpha() but returns 0 for the empty string.
498
499       "isascii"
500           ret = isascii(charstring);
501
502           POSIX.1-2008 marks it as obsolete, but I include it anyway.
503
504       "isatty"
505           ret = isatty(fd);
506
507       "isblank"
508           ret = isblank(charstring);
509
510           Like POSIX::isblank() but returns 0 for the empty string.
511
512       "iscntrl"
513           ret = iscntrl(charstring);
514
515           Like POSIX::iscntrl() but returns 0 for the empty string.
516
517       "isdigit"
518           ret = isdigit(charstring);
519
520           Like POSIX::isdigit() but returns 0 for the empty string.
521
522       "isfinite"
523           ret = isfinite(x);
524
525       "isgraph"
526           ret = isgraph(charstring);
527
528           Like POSIX::isgraph() but returns 0 for the empty string.
529
530       "isinf"
531           ret = isinf(x);
532
533       "islower"
534           ret = islower(charstring);
535
536           Like POSIX::islower() but returns 0 for the empty string.
537
538       "isnan"
539           ret = isnan(x);
540
541       "isnormal"
542           ret = isnormal(x);
543
544       "isprint"
545           ret = isprint(charstring);
546
547           Like POSIX::isprint() but returns 0 for the empty string.
548
549       "ispunct"
550           ret = ispunct(charstring);
551
552           Like POSIX::ispunct() but returns 0 for the empty string.
553
554       "isspace"
555           ret = isspace(charstring);
556
557           Like POSIX::isspace() but returns 0 for the empty string.
558
559       "isupper"
560           ret = isupper(charstring);
561
562           Like POSIX::isupper() but returns 0 for the empty string.
563
564       "isxdigit"
565           ret = isxdigit(charstring);
566
567           Like POSIX::isxdigit() but returns 0 for the empty string.
568
569       "j0"
570           y = j0(x);
571
572           j0() is the Bessel function of the first kind of order 0.
573
574       "j1"
575           y = j1(x);
576
577           j1() is the Bessel function of the first kind of order 1.
578
579       "jn"
580           y = jn(n, x);
581
582           jn() is the Bessel function of the first kind of order n.
583
584       "jrand48"
585           (r, X0, X1, X2) = jrand48(X0, X1, X2);
586
587       "killpg"
588           ret = killpg(pgrp, sig);
589
590       "l64a"
591           s = l64a(n);
592
593       "lchown"
594           ret = lchown(path, uid, gid);
595
596       "ldexp"
597           y = ldexp(x, exp);
598
599       "lgamma"
600           y = lgamma(x);
601
602       "link"
603           ret = link(path1, path2);
604
605       "linkat"
606           ret = linkat(fd1, path1, fd2, path2, flags=0);
607
608           flags can be 0 or "AT_SYMLINK_FOLLOW".
609
610       "log1p"
611           y = log1p(x);
612
613       "log2"
614           y = log2(x);
615
616       "logb"
617           y = logb(x);
618
619       "lrand48"
620           r = lrand48();
621
622       "lround"
623           l = lround(x);
624
625           Calls llround() or lround() whichever is the maximum available on
626           your system. If the rounded value is outside Perl's internal signed
627           integer range, it is returned as a string. If the rounded value is
628           too large to be stored in a long long or long, undef is returned.
629
630       "lstat"
631           (dev, ino, mode, nlink, uid, gid, rdev, size, atim_sec, mtim_sec,
632           ctim_sec, blksize, blocks, atim_nsec, mtim_nsec, ctim_nsec) =
633           lstat(path);
634
635           "path" is assumed to be a string (or will be converted to a
636           string).
637
638           See stat() for notes on the return values and bugs in CORE::stat().
639
640           Returns an empty list on error.
641
642       "mkdir"
643           ret = mkdir(path, [mode = 0777]);
644
645       "mkdirat"
646           ret = mkdirat(fd, path, mode);
647
648       "mkdtemp"
649           name = mkdtemp(template);
650
651       "mkfifo"
652           ret = mkfifo(path, mode);
653
654       "mkfifoat"
655           ret = mkfifoat(fd, path, mode);
656
657       "mknod"
658           ret = mknod(path, mode, dev);
659
660       "mknodat"
661           ret = mknodat(fd, path, mode, dev);
662
663       "mkstemp"
664           (fd, name) = mkstemp(template);
665
666       "mrand48"
667           mrand48();
668
669       "nanosleep"
670           (rem_sec, rem_nsec) = nanosleep(sec, nsec);
671
672           In scalar context returns the remaining seconds as a floating point
673           number.
674
675       "nearbyint"
676           y = nearbyint(x);
677
678       "nextafter"
679           z = nextafter(x, y);
680
681       "nexttoward"
682           z = nexttoward(x, y);
683
684       "nice"
685           ret = nice(incr);
686
687           Returns undef on error.
688
689       "nrand48"
690           r = nrand48()
691
692       "open"
693           ret = open(path, flags=O_RDONLY, mode=0666);
694
695       "openat"
696           ret = openat(dirfd, path, flags=O_RDONLY, mode=0666);
697
698           If dirfd is numeric (i.e. a file descriptor), openat() returns a
699           file descriptor. If dirfd is a file or directory handle, the return
700           value is also a handle whose type depends on the file type of path:
701           If path is a directory, the return value is a directory handle,
702           otherwise it's a file handle.
703
704           To get a handle even for the special numeric dirfd value
705           "AT_FDCWD", you can pass a reference to that value instead, i.e.
706           "openat(\AT_FDCWD, ...)".
707
708           Returns undef on error.
709
710       "openat2"
711           ret = openat2(dirfd, path, how);
712
713           The openat2() system call is a Linux-specific extension of openat()
714           and provides a superset of its functionality.
715
716           The how parameter is a hash reference corresponding to the struct
717           open_how. It currently supports the keys flags, mode and resolve.
718           Missing keys are treated as having a zero value.
719
720           Example:
721
722             my $fh = openat2(
723               \AT_FDCWD, '/foobar',
724               {flags => O_RDWR|O_CREAT, mode => 0600, resolve => RESOLVE_IN_ROOT}
725             );
726
727           Note that, unlike open() or openat(), openat2() is very picky about
728           flags and mode. See the manpage for details.
729
730           Returns undef on error.
731
732       "posix_fadvise"
733           ret = posix_fadvise(fd, offset, len, advice);
734
735           advice is one of the "POSIX_FADV_" constants.
736
737           Returns undef on error
738
739       "posix_fallocate"
740           ret = posix_fallocate(fd, offset, len);
741
742       "pread"
743           bytes_read = pread(fd, buf, count, offset=0, buf_offset=0);
744
745           pread() reads count bytes (not characters) of data from the file
746           descriptor fd at file offset offset into the scalar buf without
747           changing the file offset. buf will be enlarged automatically if
748           necessary.
749
750           offset and buf_offset are set to 0 if omitted or undef.
751
752           pread() treats buf just like sysread() does: buf_offset may be
753           specified to place the read data at that position in buf. If
754           buf_offset is past the end of buf, buf will be padded with zeros
755           before appending the data. If buf_offset is negative, it is counted
756           from the end of the string. buf will be grown or shrunk so that the
757           last byte actually read is the last byte of buf after the read.
758
759           Returns the number of bytes read, 0 at EOF, undef on error.
760
761       "preadv"
762           bytes_read = preadv(fd, buffers, sizes, offset=0);
763
764           preadv() behaves like readv() but adds an optional offset argument,
765           which specifies the file position at which the data is to be read.
766           offset is set to 0 if omitted or undef.
767
768           The file offset is not changed by this system call. The file
769           referred to by fd must be capable of seeking.
770
771           This syscall is present in Linux and BSD.
772
773       "preadv2"
774           bytes_read = preadv2(fd, buffers, sizes, offset=0, flags=0);
775
776           preadv2() is similar to preadv() but adds an optional flags
777           argument, which is a bitwise OR of zero or more of the "RWF_*"
778           flags (see the manpage for details). flags is set to 0 if omitted
779           or undef.
780
781           This syscall is Linux-specific.
782
783       "ptsname"
784           name = ptsname(fd);
785
786       "pwrite"
787           bytes_written = pwrite(fd, buf, count=undef, offset=0,
788           buf_offset=0);
789
790           pwrite() writes count bytes of data from the scalar buf to the file
791           descriptor fd at file offset offset without changing the file
792           offset. The file referenced by fd must be capable of seeking.
793
794           If count is omitted or undef, everything from buf_offset up to the
795           end of buf is written.
796
797           buf_offset may be specified to write data from that position in
798           buf. If buf_offset is negative it is counted from the end of the
799           string.
800
801           offset and buf_offset are set to 0 if omitted or undef.
802
803           Returns the number of bytes written, undef on error.
804
805           On Linux, if a file is opened with "O_APPEND", pwrite() appends
806           data to the end of the file, regardless of the value of offset (in
807           violation of POSIX).
808
809       "pwritev"
810           bytes_written = pwritev(fd, buffers, offset=0);
811
812           pwritev() behaves like writev() but adds an optional offset
813           argument, which specifies the file position at which the data is to
814           be written. offset is set to 0 if omitted or undef.
815
816           The file offset is not changed by this system call. The file
817           referred to by fd must be capable of seeking.
818
819           On Linux, if a file is opened with "O_APPEND", pwritev() appends
820           data to the end of the file, regardless of the value of offset (in
821           violation of POSIX).
822
823           This syscall is present in Linux and BSD.
824
825       "pwritev2"
826           bytes_written = pwritev2(fd, buffers, offset=0, flags=0);
827
828           pwritev2() is similar to pwritev() but adds an optional flags
829           argument, which is a bitwise OR of zero or more of the "RWF_*"
830           flags (see the manpage for details). flags is set to 0 if omitted
831           or undef.
832
833           This syscall is Linux-specific.
834
835       "random"
836           r = random();
837
838       "read"
839           bytes_read = read(fd, buf, count);
840
841           Like POSIX::read() but returns 0 at EOF instead of "0 but true".
842
843       "readv"
844           bytes_read = readv(fd, buffers, sizes);
845
846           Example:
847
848             my $fh = openat(\AT_FDCWD, '/tmp/foobar', O_RDWR|O_CREAT|O_TRUNC);
849             pwrite($fh, 'foobar', 6, 0);
850             readv($fh, my @buf, [4, 0, 4, 4]);
851             # -> @buf is ('foob', '', 'ar')
852
853           readv() reads from the file descriptor fd into buffers as many
854           strings as there are elements in sizes.
855
856           buffers must be a variable holding either an array or an array
857           reference, i.e. @buf or $buf.
858
859           sizes must be an array reference, i.e. "\@sizes", $sizes, or
860           "[...]".
861
862           sizes is expected to hold unsigned integers that specify how many
863           bytes are to be read into each buffer. A byte count of 0 or undef
864           creates an empty string. sizes is processed in array order.
865
866           buffers will be extended if necessary, but it will never be shrunk.
867           If buffers is not empty, any existing elements are replaced as long
868           as sufficient data was read from fd.
869
870           If the total byte count of sizes exceeds the number of bytes
871           actually read from fd, there may be one partly filled buffer and
872           the rest of sizes is skipped, so you may end up with less strings
873           in buffers than there are elements in sizes.
874
875           readv() returns the number of bytes read (which may be less than
876           the total bytes in sizes) or undef on error.
877
878       "readlink"
879           name = readlink(path);
880
881           Returns undef on error.
882
883       "readlinkat"
884           name = readlinkat(dirfd, path);
885
886           Returns undef on error.
887
888       "realpath"
889           resolved_path = realpath(path);
890
891           Calls the actual C library fuction realpath() and relies on it to
892           be able to allocate memory for the resolved path automatically (as
893           required by POSIX-2008).
894
895           Returns undef on error.
896
897       "remainder"
898           rem = remainder(x, y);
899
900           Returns  undef on error.
901
902       "remove"
903           ret = remove(path);
904
905           Calls the actual C library function remove().
906
907           Note that core POSIX::remove() fails if path is a symlink to a
908           directory because someone "couldn't read the plans right and did a
909           piss-poor job of putting it together" as (-d $_[0]) ?
910           CORE::rmdir($_[0]) : CORE::unlink($_[0]). Quote from Armageddon.
911
912           This could be fixed like this: "unlink $_[0] or ($!{EISDIR} or
913           $!{EPERM}) and rmdir $_[0]" (correct errno check depends on OS), or
914           by using the library call right away.
915
916       "remquo"
917           (rem, quo) = remquo(x, y);
918
919           Returns an empty list on error.
920
921       "rename"
922           ret = rename(old, new);
923
924       "renameat"
925           ret = renameat(olddirfd, oldpath, newdirfd, newpath);
926
927       "renameat2"
928           ret = renameat(olddirfd, oldpath, newdirfd, newpath, flags=0);
929
930           The renameat2() system call is a Linux-specific extension of
931           renameat() and provides a superset of its functionality.
932
933           flags is the bitwise OR of zero or more of "RENAME_EXCHANGE",
934           "RENAME_NOREPLACE", "RENAME_WHITEOUT".
935
936       "round"
937           r = round(x);
938
939       "scalbn"
940           y = scalbn(x, n);
941
942           Calls scalbln() or scalbn(), whichever is the maximum supported by
943           your system.
944
945       "seed48"
946           (old_seed1, old_seed2, old_seed3) = seed48(seed1, seed2, seed3);
947
948       "setegid"
949           ret = setegid(gid);
950
951       "seteuid"
952           ret = seteuid(uid);
953
954       "setgid"
955           ret = setgid(gid);
956
957       "setitimer"
958           (old_int_sec, old_int_usec, old_val_sec, old_val_usec) =
959           setitimer(which, int_sec, int_usec, val_sec, val_usec);
960
961           which is one of "ITIMER_REAL", "ITIMER_VIRTUAL", "ITIMER_PROF".
962
963       "setpriority"
964           ret = setpriority(prio, which=PRIO_PROCESS, who=0);
965
966           which can be one of "PRIO_PROCESS", "PRIO_PGRP", "PRIO_USER",
967           defaults to "PRIO_PROCESS". who defaults to 0.
968
969           Note that due to the support of default values for which and who,
970           prio is the first call parameter, whereas in the actual syscall it
971           is the last.
972
973           Returns true on success, undef on error.
974
975       "setregid"
976           ret = setregid(rgid, egid);
977
978       "setreuid"
979           ret = setreuid(ruid, euid);
980
981       "setsid"
982           sid = setsid();
983
984       "setuid"
985           ret = setuid(uid);
986
987       "setutxent"
988           setutxent();
989
990       "sighold"
991           ret = sighold(sig);
992
993       "sigignore"
994           ret = sigignore(sig);
995
996       "signbit"
997           b = signbit(x);
998
999       "sigpause"
1000           sigpause(sig);
1001
1002       "sigrelse"
1003           ret = sigrelse(sig);
1004
1005       "sin"
1006           y = sin(x);
1007
1008       "sinh"
1009           y = sinh(x);
1010
1011       "srand48"
1012           srand48(seedval);
1013
1014       "srandom"
1015           srandom(seed);
1016
1017       "stat"
1018           (dev, ino, mode, nlink, uid, gid, rdev, size, atim_sec, mtim_sec,
1019           ctim_sec, blksize, blocks, atim_nsec, mtim_nsec, ctim_nsec) =
1020           stat(what);
1021
1022           "what" can be a path, a Perl file handle or a file descriptor.
1023
1024           "ctim_sec", "blksize", "blocks" and nanoseconds may not be
1025           available on your system. Values outside Perl's internal integer
1026           range are returned as strings, i.e. if you need the exact values
1027           you should, for example, use "eq" instead of "==" for comparisons.
1028
1029           Note that CORE::stat() lies to you in some cases: It returns rdev
1030           as a signed integer even if your OS's "dev_t" is unsigned. It
1031           returns size as a floating point number if your OS's "off_t" is
1032           bigger than Perl's integer size. It returns the times as floating
1033           point numbers if your OS's "time_t" is unsigned.
1034
1035           POSIX::2008::stat() doesn't mimic these bugs and uses the correct
1036           data types for all values.
1037
1038           Returns an empty list on error.
1039
1040       "strptime"
1041           (sec, min, hour, mday, mon, year, wday, yday, isdst) = strptime(s,
1042           format[, sec, min, hour, mday, mon, year, wday, yday, isdst]);
1043
1044           strptime() converts the string s into a broken-down time according
1045           to the format string format. The time fields may optionally be
1046           initialized in whole or in part and will be returned as initialized
1047           if they are not affected by the format string. Unprocessed
1048           uninitialized or undef fields are returned as undef.
1049
1050           Returns an empty list on error.
1051
1052           In scalar context returns the index of the first byte in s that was
1053           not processed or the byte length of s if the whole string was
1054           consumed or undef on error.
1055
1056           As strptime() acts on null-terminated strings, strings containing
1057           NUL bytes will only be processed up to the first NUL byte.
1058
1059       "symlink"
1060           ret = symlink(target, linkpath);
1061
1062       "symlinkat"
1063           ret = symlinkat(target, dirfd, linkpath);
1064
1065       "sync"
1066           sync();
1067
1068       "tan"
1069           y = tan(x);
1070
1071       "tanh"
1072           y = tanh(x);
1073
1074       "tgamma"
1075           y = tgamma(x);
1076
1077       "timer_create"
1078           timerid = timer_create(clockid, signal);
1079
1080           Returns undef on error.
1081
1082       "timer_delete"
1083           ret = timer_delete(timerid);
1084
1085           Returns "0 but true" on success, undef on error.
1086
1087       "timer_getoverrun"
1088           count = timer_getoverrun(timerid);
1089
1090           Returns undef on error.
1091
1092       "timer_gettime"
1093           (interval_sec, interval_nsec, initial_sec, initial_nsec) =
1094           timer_gettime(timerid);
1095
1096           Returns an empty list on error.
1097
1098       "timer_settime"
1099           (old_int_sec, old_int_nsec, old_init_sec, old_init_nsec) =
1100           timer_settime(timerid, flags, int_sec, int_nsec, [init_sec,
1101           init_nsec]);
1102
1103           flags may be 0 or "TIMER_ABSTIME". If the init values are omitted,
1104           they are set to the int values.
1105
1106       "truncate"
1107           ret = truncate(path, length);
1108
1109       "trunc"
1110           y = trunc(x);
1111
1112       "ttyname"
1113           name = ttyname(fd);
1114
1115       "unlink"
1116           ret = unlink(path);
1117
1118           Calls the actual C library function unlink().
1119
1120           Note that core POSIX::unlink() calls CORE::unlink(), which, unless
1121           you start Perl with "-U", a) is prone to time-of-check/time-of-use
1122           race conditions due to an additional lstat(), and b) blindly fails
1123           with "EISDIR" for directories (due to said lstat()), ignoring that
1124           some OSes use "EPERM" in this case (as required by POSIX).
1125
1126       "unlinkat"
1127           ret = unlinkat(dirfd, path, flags=0);
1128
1129           flags can be 0 or "AT_REMOVEDIR".
1130
1131       "utimensat"
1132           ret = utimensat(dirfd, path, flags, atime_sec, atime_nsec,
1133           mtime_sec, mtime_nsec);
1134
1135           flags can be 0 or "AT_SYMLINK_NOFOLLOW", defaults to 0.
1136
1137           atime_sec and mtime_sec default to 0. atime_nsec and mtime_nsec
1138           default to "UTIME_NOW".
1139
1140       "write"
1141           bytes_written = write(fd, buf, count=undef);
1142
1143           Like POSIX::write() but returns 0 instead of "0 but true" if 0
1144           bytes were written, and never writes more bytes than buf contains
1145           even if count exceeds the length of buf.
1146
1147           If count is omitted or undef, it defaults to the length of buf.
1148
1149       "writev"
1150           bytes_written = writev(fd, buffers);
1151
1152           writev() writes multiple buffers of data to the file associated
1153           with the file descriptor fd.
1154
1155           buffers must be an array reference, i.e. "\@buf", $buf or "[...]".
1156           The buffers are processed in array order. Undefined or empty
1157           elements are skipped.
1158
1159           Returns the number of bytes written or undef on error.
1160
1161       "y0"
1162           y = y0(x);
1163
1164           y0() is the Bessel function of the second kind of order 0.
1165
1166       "y1"
1167           y = y1(x);
1168
1169           y1() is the Bessel function of the second kind of order 1.
1170
1171       "yn"
1172           y = yn(n, x);
1173
1174           yn() is the Bessel function of the second kind of order n.
1175

EXPORTS

1177       This module does not export anything by default. The following export
1178       tags are available:
1179
1180        :at     All *at() functions like openat() and all AT_/RENAME_/RESOLVE_ constants
1181        :id     All get/set*id() functions like getuid() etc.
1182        :is     All is* functions like isdigit() etc.
1183        :rw     read(), readv(), write(), writev()
1184        :prw    pread(), preadv(), preadv2(), pwrite(), pwritev(), pwritev2()
1185        :clock  All clock* functions and CLOCK_ constants
1186        :fcntl  All F_, FD_, O_, POSIX_FADV_, SEEK_ and _OK constants (for AT_ use :at)
1187        :fenv_h All FE_ constants and fe* functions
1188        :fnm    fnmatch() and all FNM_ constants
1189        :stat_h All S_I* and UTIME_ constants
1190        :time_h All CLOCK_ and TIMER_ constants
1191        :timer  All timer_ functions and TIMER_ constants
1192

CONSTANTS

1194       "AT_EACCESS" "AT_EMPTY_PATH" "AT_FDCWD" "AT_NO_AUTOMOUNT"
1195       "AT_REMOVEDIR" "AT_SYMLINK_FOLLOW" "AT_SYMLINK_NOFOLLOW"
1196       "RENAME_EXCHANGE" "RENAME_NOREPLACE" "RENAME_WHITEOUT"
1197       "RESOLVE_BENEATH" "RESOLVE_CACHED" "RESOLVE_IN_ROOT"
1198       "RESOLVE_NO_MAGICLINKS" "RESOLVE_NO_SYMLINKS" "RESOLVE_NO_XDEV"
1199
1200       "BOOT_TIME" "NEW_TIME" "OLD_TIME" "DEAD_PROCESS" "INIT_PROCESS"
1201       "LOGIN_PROCESS" "USER_PROCESS" "RUN_LVL"
1202
1203       "CLOCK_BOOTTIME" "CLOCK_HIGHRES" "CLOCK_MONOTONIC"
1204       "CLOCK_MONOTONIC_COARSE" "CLOCK_MONOTONIC_FAST"
1205       "CLOCK_MONOTONIC_PRECISE" "CLOCK_MONOTONIC_RAW"
1206       "CLOCK_PROCESS_CPUTIME_ID" "CLOCK_REALTIME" "CLOCK_REALTIME_COARSE"
1207       "CLOCK_REALTIME_FAST" "CLOCK_REALTIME_PRECISE" "CLOCK_SOFTTIME"
1208       "CLOCK_THREAD_CPUTIME_ID" "CLOCK_UPTIME" "CLOCK_UPTIME_FAST"
1209       "CLOCK_UPTIME_PRECISE"
1210
1211       "_CS_GNU_LIBC_VERSION" "_CS_GNU_LIBPTHREAD_VERSION" "_CS_PATH"
1212
1213       "F_DUPFD" "F_DUPFD_CLOEXEC" "F_GETFD" "F_SETFD" "F_GETFL" "F_SETFL"
1214       "F_GETLK" "F_SETLK" "F_SETLKW" "F_GETOWN" "F_SETOWN" "F_RDLCK"
1215       "F_UNLCK" "F_WRLCK"
1216
1217       "FE_TONEAREST" "FE_TOWARDZERO" "FE_UPWARD" "FE_DOWNWARD"
1218
1219       "FD_CLOEXEC"
1220
1221       "FNM_CASEFOLD" "FNM_FILE_NAME" "FNM_LEADING_DIR" "FNM_NOESCAPE"
1222       "FNM_NOMATCH" "FNM_PATHNAME" "FNM_PERIOD"
1223
1224       "FP_INFINITE" "FP_NAN" "FP_NORMAL" "FP_SUBNORMAL" "FP_ZERO"
1225
1226       "TIMER_ABSTIME" "ITIMER_PROF" "ITIMER_REAL" "ITIMER_VIRTUAL"
1227
1228       "O_ACCMODE" "O_APPEND" "O_ASYNC" "O_CLOEXEC" "O_CREAT" "O_DIRECT"
1229       "O_DIRECTORY" "O_DSYNC" "O_EXCL" "O_EXEC" "O_LARGEFILE" "O_NDELAY"
1230       "O_NOATIME" "O_NOCTTY" "O_NOFOLLOW" "O_NONBLOCK" "O_PATH" "O_RDONLY"
1231       "O_RDWR" "O_RSYNC" "O_SEARCH" "O_SYNC" "O_TMPFILE" "O_TRUNC"
1232       "O_TTY_INIT" "O_WRONLY" "FASYNC"
1233
1234       "POSIX_FADV_NORMAL" "POSIX_FADV_SEQUENTIAL" "POSIX_FADV_RANDOM"
1235       "POSIX_FADV_NOREUSE" "POSIX_FADV_WILLNEED" "POSIX_FADV_DONTNEED"
1236
1237       "PRIO_PROCESS" "PRIO_PGRP" "PRIO_USER"
1238
1239       "RTLD_GLOBAL" "RTLD_LAZY" "RTLD_LOCAL" "RTLD_NOW"
1240
1241       "RWF_APPEND" "RWF_DSYNC" "RWF_HIPRI" "RWF_NOWAIT" "RWF_SYNC"
1242
1243       "SEEK_SET" "SEEK_CUR" "SEEK_END" "SEEK_DATA" "SEEK_HOLE" "F_OK" "R_OK"
1244       "W_OK" "X_OK"
1245
1246       "S_IFMT" "S_IFBLK" "S_IFCHR" "S_IFIFO" "S_IFREG" "S_IFDIR" "S_IFLNK"
1247       "S_IFSOCK" "S_ISUID" "S_ISGID" "S_IRWXU" "S_IRUSR" "S_IWUSR" "S_IXUSR"
1248       "S_IRWXG" "S_IRGRP" "S_IWGRP" "S_IXGRP" "S_IRWXO" "S_IROTH" "S_IWOTH"
1249       "S_IXOTH" "S_ISVTX"
1250
1251       "UTIME_NOW" "UTIME_OMIT"
1252

NOTES

1254       preadv() and pwritev() are nonstandard extensions present in Linux and
1255       BSD.
1256
1257       openat2(), preadv2(), pwritev2() and renameat2() are nonstandard
1258       extensions present in Linux.
1259
1260       fstatat(), lstat() and stat() do not set the special underscore
1261       filehandle "_" (mostly because I have no clue how that works).
1262
1263       open(), openat() and openat2() do not set the "O_CLOEXEC" flag
1264       automatically. You have to take care of that yourself if needed.
1265
1266       isalnum() and friends were cowardly removed from the POSIX module with
1267       Perl 5.24.0. They have found a cozy home here with a fix for a long-
1268       standing bug.
1269
1270       "SEEK_DATA" and "SEEK_HOLE" are nonstandard extensions present in
1271       Linux, Solaris, FreeBSD, and DragonFly BSD; they are proposed for
1272       inclusion in the next POSIX revision (Issue 8).
1273

AUTHOR

1275       Initially hacked together by Carsten Gaebler.
1276

LICENSE

1278       This library is free software. You can redistribute and/or modify it
1279       under the terms of the Do What The Fuck You Want To Public License,
1280       Version 2, as published by Sam Hocevar. See the COPYING file or
1281       <http://www.wtfpl.net/> for more details.
1282
1283
1284
1285perl v5.38.0                      2023-11-20                    POSIX::2008(3)