ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-AIO/README
(Generate patch)

Comparing IO-AIO/README (file contents):
Revision 1.62 by root, Sat Aug 25 19:59:18 2018 UTC vs.
Revision 1.70 by root, Sat Apr 1 02:14:05 2023 UTC

… …
221 IO::AIO::idle_timeout $seconds 221 IO::AIO::idle_timeout $seconds
222 IO::AIO::max_outstanding $maxreqs 222 IO::AIO::max_outstanding $maxreqs
223 IO::AIO::nreqs 223 IO::AIO::nreqs
224 IO::AIO::nready 224 IO::AIO::nready
225 IO::AIO::npending 225 IO::AIO::npending
226 IO::AIO::reinit
227
226 $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL] 228 $nfd = IO::AIO::get_fdlimit
227 IO::AIO::min_fdlimit $nfd [EXPERIMENTAL] 229 IO::AIO::min_fdlimit $nfd
228 230
229 IO::AIO::sendfile $ofh, $ifh, $offset, $count 231 IO::AIO::sendfile $ofh, $ifh, $offset, $count
230 IO::AIO::fadvise $fh, $offset, $len, $advice 232 IO::AIO::fadvise $fh, $offset, $len, $advice
233 IO::AIO::fexecve $fh, $argv, $envp
234
231 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] 235 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
232 IO::AIO::munmap $scalar 236 IO::AIO::munmap $scalar
233 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address] 237 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
234 IO::AIO::madvise $scalar, $offset, $length, $advice 238 IO::AIO::madvise $scalar, $offset, $length, $advice
235 IO::AIO::mprotect $scalar, $offset, $length, $protect 239 IO::AIO::mprotect $scalar, $offset, $length, $protect
236 IO::AIO::munlock $scalar, $offset = 0, $length = undef 240 IO::AIO::munlock $scalar, $offset = 0, $length = undef
237 IO::AIO::munlockall 241 IO::AIO::munlockall
242
243 # stat extensions
244 $counter = IO::AIO::st_gen
245 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
246 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
247 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
248 $seconds = IO::AIO::st_btimesec
249 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
250
251 # very much unportable syscalls
252 IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
253 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
254 IO::AIO::tee $r_fh, $w_fh, $length, $flags
255
256 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
257 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
258
259 $fh = IO::AIO::eventfd [$initval, [$flags]]
260 $fh = IO::AIO::memfd_create $pathname[, $flags]
261
262 $fh = IO::AIO::timerfd_create $clockid[, $flags]
263 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
264 ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
265
266 $fh = IO::AIO::pidfd_open $pid[, $flags]
267 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
268 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
269
270 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
271 $retval = IO::AIO::umount $path, $flags = 0
238 272
239 API NOTES 273 API NOTES
240 All the "aio_*" calls are more or less thin wrappers around the syscall 274 All the "aio_*" calls are more or less thin wrappers around the syscall
241 with the same name (sans "aio_"). The arguments are similar or 275 with the same name (sans "aio_"). The arguments are similar or
242 identical, and they all accept an additional (and optional) $callback 276 identical, and they all accept an additional (and optional) $callback
… …
309 aio_open $pathname, $flags, $mode, $callback->($fh) 343 aio_open $pathname, $flags, $mode, $callback->($fh)
310 Asynchronously open or create a file and call the callback with a 344 Asynchronously open or create a file and call the callback with a
311 newly created filehandle for the file (or "undef" in case of an 345 newly created filehandle for the file (or "undef" in case of an
312 error). 346 error).
313 347
314 The pathname passed to "aio_open" must be absolute. See API NOTES,
315 above, for an explanation.
316
317 The $flags argument is a bitmask. See the "Fcntl" module for a list. 348 The $flags argument is a bitmask. See the "Fcntl" module for a list.
318 They are the same as used by "sysopen". 349 They are the same as used by "sysopen".
319 350
320 Likewise, $mode specifies the mode of the newly created file, if it 351 Likewise, $mode specifies the mode of the newly created file, if it
321 didn't exist and "O_CREAT" has been given, just like perl's 352 didn't exist and "O_CREAT" has been given, just like perl's
… …
473 aio_lstat $fh, $callback->($status) 504 aio_lstat $fh, $callback->($status)
474 Works almost exactly like perl's "stat" or "lstat" in void context. 505 Works almost exactly like perl's "stat" or "lstat" in void context.
475 The callback will be called after the stat and the results will be 506 The callback will be called after the stat and the results will be
476 available using "stat _" or "-s _" and other tests (with the 507 available using "stat _" or "-s _" and other tests (with the
477 exception of "-B" and "-T"). 508 exception of "-B" and "-T").
478
479 The pathname passed to "aio_stat" must be absolute. See API NOTES,
480 above, for an explanation.
481 509
482 Currently, the stats are always 64-bit-stats, i.e. instead of 510 Currently, the stats are always 64-bit-stats, i.e. instead of
483 returning an error when stat'ing a large file, the results will be 511 returning an error when stat'ing a large file, the results will be
484 silently truncated unless perl itself is compiled with large file 512 silently truncated unless perl itself is compiled with large file
485 support. 513 support.
… …
887 So in general, you should only use these calls for things that do 915 So in general, you should only use these calls for things that do
888 (filesystem) I/O, not for things that wait for other events 916 (filesystem) I/O, not for things that wait for other events
889 (network, other processes), although if you are careful and know 917 (network, other processes), although if you are careful and know
890 what you are doing, you still can. 918 what you are doing, you still can.
891 919
892 The following constants are available (missing ones are, as usual 920 The following constants are available and can be used for normal
893 0): 921 "ioctl" and "fcntl" as well (missing ones are, as usual 0):
894 922
895 "F_DUPFD_CLOEXEC", 923 "F_DUPFD_CLOEXEC",
896 924
897 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW", 925 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
898 926
899 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE", 927 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
900 "FIDEDUPERANGE". 928 "FIDEDUPERANGE".
929
930 "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
931 "F_SEAL_GROW" and "F_SEAL_WRITE".
901 932
902 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION", 933 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
903 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP". 934 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
904 935
905 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR", 936 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
… …
916 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME", 947 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
917 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT", 948 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
918 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT", 949 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
919 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX", 950 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
920 "FS_XFLAG_HASATTR", 951 "FS_XFLAG_HASATTR",
952
953 "BLKROSET", "BLKROGET", "BLKRRPART", "BLKGETSIZE", "BLKFLSBUF",
954 "BLKRASET", "BLKRAGET", "BLKFRASET", "BLKFRAGET", "BLKSECTSET",
955 "BLKSECTGET", "BLKSSZGET", "BLKBSZGET", "BLKBSZSET", "BLKGETSIZE64",
921 956
922 aio_sync $callback->($status) 957 aio_sync $callback->($status)
923 Asynchronously call sync and call the callback when finished. 958 Asynchronously call sync and call the callback when finished.
924 959
925 aio_fsync $fh, $callback->($status) 960 aio_fsync $fh, $callback->($status)
… …
1016 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh; 1051 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1017 aio_mlock $data; # mlock in background 1052 aio_mlock $data; # mlock in background
1018 1053
1019 aio_mlockall $flags, $callback->($status) 1054 aio_mlockall $flags, $callback->($status)
1020 Calls the "mlockall" function with the given $flags (a combination 1055 Calls the "mlockall" function with the given $flags (a combination
1021 of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE"). 1056 of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
1057 "IO::AIO::MCL_ONFAULT").
1022 1058
1023 On systems that do not implement "mlockall", this function returns 1059 On systems that do not implement "mlockall", this function returns
1024 -1 and sets errno to "ENOSYS". 1060 -1 and sets errno to "ENOSYS". Similarly, flag combinations not
1061 supported by the system result in a return value of -1 with errno
1062 being set to "EINVAL".
1025 1063
1026 Note that the corresponding "munlockall" is synchronous and is 1064 Note that the corresponding "munlockall" is synchronous and is
1027 documented under "MISCELLANEOUS FUNCTIONS". 1065 documented under "MISCELLANEOUS FUNCTIONS".
1028 1066
1029 Example: asynchronously lock all current and future pages into 1067 Example: asynchronously lock all current and future pages into
… …
1218 fails the request with "ENOENT", there is often no need for error 1256 fails the request with "ENOENT", there is often no need for error
1219 checking in the "aio_wd" callback, as future requests using the 1257 checking in the "aio_wd" callback, as future requests using the
1220 value will fail in the expected way. 1258 value will fail in the expected way.
1221 1259
1222 IO::AIO::CWD 1260 IO::AIO::CWD
1223 This is a compiletime constant (object) that represents the process 1261 This is a compile time constant (object) that represents the process
1224 current working directory. 1262 current working directory.
1225 1263
1226 Specifying this object as working directory object for a pathname is 1264 Specifying this object as working directory object for a pathname is
1227 as if the pathname would be specified directly, without a directory 1265 as if the pathname would be specified directly, without a directory
1228 object. For example, these calls are functionally identical: 1266 object. For example, these calls are functionally identical:
… …
1562 no longer exceeded. 1600 no longer exceeded.
1563 1601
1564 In other words, this setting does not enforce a queue limit, but can 1602 In other words, this setting does not enforce a queue limit, but can
1565 be used to make poll functions block if the limit is exceeded. 1603 be used to make poll functions block if the limit is exceeded.
1566 1604
1567 This is a very bad function to use in interactive programs because 1605 This is a bad function to use in interactive programs because it
1568 it blocks, and a bad way to reduce concurrency because it is 1606 blocks, and a bad way to reduce concurrency because it is inexact.
1569 inexact: Better use an "aio_group" together with a feed callback. 1607 If you need to issue many requests without being able to call a poll
1608 function on demand, it is better to use an "aio_group" together with
1609 a feed callback.
1570 1610
1571 Its main use is in scripts without an event loop - when you want to 1611 Its main use is in scripts without an event loop - when you want to
1572 stat a lot of files, you can write something like this: 1612 stat a lot of files, you can write something like this:
1573 1613
1574 IO::AIO::max_outstanding 32; 1614 IO::AIO::max_outstanding 32;
… …
1579 } 1619 }
1580 1620
1581 IO::AIO::flush; 1621 IO::AIO::flush;
1582 1622
1583 The call to "poll_cb" inside the loop will normally return 1623 The call to "poll_cb" inside the loop will normally return
1584 instantly, but as soon as more thna 32 reqeusts are in-flight, it 1624 instantly, allowing the loop to progress, but as soon as more than
1585 will block until some requests have been handled. This keeps the 1625 32 requests are in-flight, it will block until some requests have
1586 loop from pushing a large number of "aio_stat" requests onto the 1626 been handled. This keeps the loop from pushing a large number of
1587 queue. 1627 "aio_stat" requests onto the queue (which, with many paths to stat,
1628 can use up a lot of memory).
1588 1629
1589 The default value for "max_outstanding" is very large, so there is 1630 The default value for "max_outstanding" is very large, so there is
1590 no practical limit on the number of outstanding requests. 1631 no practical limit on the number of outstanding requests.
1591 1632
1592 STATISTICAL INFORMATION 1633 STATISTICAL INFORMATION
… …
1638 below, for full accuracy. 1679 below, for full accuracy.
1639 1680
1640 File birth time is only available when the OS and perl support it 1681 File birth time is only available when the OS and perl support it
1641 (on FreeBSD and NetBSD at the time of this writing, although support 1682 (on FreeBSD and NetBSD at the time of this writing, although support
1642 is adaptive, so if your OS/perl gains support, IO::AIO can take 1683 is adaptive, so if your OS/perl gains support, IO::AIO can take
1643 avdantage of it). On systems where it isn't available, 0 is 1684 advantage of it). On systems where it isn't available, 0 is
1644 currently returned, but this might change to "undef" in a future 1685 currently returned, but this might change to "undef" in a future
1645 version. 1686 version.
1646 1687
1647 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime 1688 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1648 Returns access, modification, change and birth time all in one go, 1689 Returns access, modification, change and birth time all in one go,
… …
1664 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec 1705 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1665 Like the functions above, but returns all four times in one go (and 1706 Like the functions above, but returns all four times in one go (and
1666 maybe more in future versions). 1707 maybe more in future versions).
1667 1708
1668 $counter = IO::AIO::st_gen 1709 $counter = IO::AIO::st_gen
1669 Returns the generation counter of the file. This is only available 1710 Returns the generation counter (in practice this is just a random
1670 on platforms which have this member in their "struct stat" (most 1711 number) of the file. This is only available on platforms which have
1671 BSDs at the time of this writing) and generally only to the root 1712 this member in their "struct stat" (most BSDs at the time of this
1672 usert. If unsupported, 0 is returned, but this might change to 1713 writing) and generally only to the root usert. If unsupported, 0 is
1673 "undef" in a future version. 1714 returned, but this might change to "undef" in a future version.
1674 1715
1675 Example: print the high resolution modification time of /etc, using 1716 Example: print the high resolution modification time of /etc, using
1676 "stat", and "IO::AIO::aio_stat". 1717 "stat", and "IO::AIO::aio_stat".
1677 1718
1678 if (stat "/etc") { 1719 if (stat "/etc") {
… …
1697 IO::AIO implements some functions that are useful when you want to use 1738 IO::AIO implements some functions that are useful when you want to use
1698 some "Advanced I/O" function not available to in Perl, without going the 1739 some "Advanced I/O" function not available to in Perl, without going the
1699 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" 1740 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1700 counterpart. 1741 counterpart.
1701 1742
1743 $retval = IO::AIO::fexecve $fh, $argv, $envp
1744 A more-or-less direct equivalent to the POSIX "fexecve" functions,
1745 which allows you to specify the program to be executed via a file
1746 descriptor (or handle). Returns -1 and sets errno to "ENOSYS" if not
1747 available.
1748
1749 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data =
1750 undef
1751 Calls the GNU/Linux mount syscall with the given arguments. All
1752 except $flags are strings, and if $data is "undef", a "NULL" will be
1753 passed.
1754
1755 The following values for $flags are available:
1756
1757 "IO::AIO::MS_RDONLY", "IO::AIO::MS_NOSUID", "IO::AIO::MS_NODEV",
1758 "IO::AIO::MS_NOEXEC", "IO::AIO::MS_SYNCHRONOUS",
1759 "IO::AIO::MS_REMOUNT", "IO::AIO::MS_MANDLOCK",
1760 "IO::AIO::MS_DIRSYNC", "IO::AIO::MS_NOATIME",
1761 "IO::AIO::MS_NODIRATIME", "IO::AIO::MS_BIND", "IO::AIO::MS_MOVE",
1762 "IO::AIO::MS_REC", "IO::AIO::MS_SILENT", "IO::AIO::MS_POSIXACL",
1763 "IO::AIO::MS_UNBINDABLE", "IO::AIO::MS_PRIVATE",
1764 "IO::AIO::MS_SLAVE", "IO::AIO::MS_SHARED", "IO::AIO::MS_RELATIME",
1765 "IO::AIO::MS_KERNMOUNT", "IO::AIO::MS_I_VERSION",
1766 "IO::AIO::MS_STRICTATIME", "IO::AIO::MS_LAZYTIME",
1767 "IO::AIO::MS_ACTIVE", "IO::AIO::MS_NOUSER", "IO::AIO::MS_RMT_MASK",
1768 "IO::AIO::MS_MGC_VAL" and "IO::AIO::MS_MGC_MSK".
1769
1770 $retval = IO::AIO::umount $path, $flags = 0
1771 Invokes the GNU/Linux "umount" or "umount2" syscalls. Always calls
1772 "umount" if $flags is 0, otherwqise always tries to call "umount2".
1773
1774 The following $flags are available:
1775
1776 "IO::AIO::MNT_FORCE", "IO::AIO::MNT_DETACH", "IO::AIO::MNT_EXPIRE"
1777 and "IO::AIO::UMOUNT_NOFOLLOW".
1778
1702 $numfd = IO::AIO::get_fdlimit 1779 $numfd = IO::AIO::get_fdlimit
1703 This function is *EXPERIMENTAL* and subject to change.
1704
1705 Tries to find the current file descriptor limit and returns it, or 1780 Tries to find the current file descriptor limit and returns it, or
1706 "undef" and sets $! in case of an error. The limit is one larger 1781 "undef" and sets $! in case of an error. The limit is one larger
1707 than the highest valid file descriptor number. 1782 than the highest valid file descriptor number.
1708 1783
1709 IO::AIO::min_fdlimit [$numfd] 1784 IO::AIO::min_fdlimit [$numfd]
1710 This function is *EXPERIMENTAL* and subject to change.
1711
1712 Try to increase the current file descriptor limit(s) to at least 1785 Try to increase the current file descriptor limit(s) to at least
1713 $numfd by changing the soft or hard file descriptor resource limit. 1786 $numfd by changing the soft or hard file descriptor resource limit.
1714 If $numfd is missing, it will try to set a very high limit, although 1787 If $numfd is missing, it will try to set a very high limit, although
1715 this is not recommended when you know the actual minimum that you 1788 this is not recommended when you know the actual minimum that you
1716 require. 1789 require.
… …
1803 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to 1876 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1804 "MAP_ANON" if your system only provides this constant), 1877 "MAP_ANON" if your system only provides this constant),
1805 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", 1878 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1806 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", 1879 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1807 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", 1880 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1808 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or 1881 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1809 "IO::AIO::MAP_STACK". 1882 "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
1883 "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1810 1884
1811 If $fh is "undef", then a file descriptor of -1 is passed. 1885 If $fh is "undef", then a file descriptor of -1 is passed.
1812 1886
1813 $offset is the offset from the start of the file - it generally must 1887 $offset is the offset from the start of the file - it generally must
1814 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0. 1888 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
… …
1851 version. 1925 version.
1852 1926
1853 On systems where this call is not supported or is not emulated, this 1927 On systems where this call is not supported or is not emulated, this
1854 call returns falls and sets $! to "ENOSYS". 1928 call returns falls and sets $! to "ENOSYS".
1855 1929
1930 IO::AIO::mlockall $flags
1931 Calls the "eio_mlockall_sync" function, which is like
1932 "aio_mlockall", but is blocking.
1933
1856 IO::AIO::munlock $scalar, $offset = 0, $length = undef 1934 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1857 Calls the "munlock" function, undoing the effects of a previous 1935 Calls the "munlock" function, undoing the effects of a previous
1858 "aio_mlock" call (see its description for details). 1936 "aio_mlock" call (see its description for details).
1859 1937
1860 IO::AIO::munlockall 1938 IO::AIO::munlockall
1861 Calls the "munlockall" function. 1939 Calls the "munlockall" function.
1862 1940
1863 On systems that do not implement "munlockall", this function returns 1941 On systems that do not implement "munlockall", this function returns
1864 ENOSYS, otherwise the return value of "munlockall". 1942 ENOSYS, otherwise the return value of "munlockall".
1943
1944 $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
1945 Uses the GNU/Linux accept4(2) syscall, if available, to accept a
1946 socket and return the new file handle on success, or sets $! and
1947 returns "undef" on error.
1948
1949 The remote name of the new socket will be stored in $sockaddr, which
1950 will be extended to allow for at least $sockaddr_maxlen octets. If
1951 the socket name does not fit into $sockaddr_maxlen octets, this is
1952 signaled by returning a longer string in $sockaddr, which might or
1953 might not be truncated.
1954
1955 To accept name-less sockets, use "undef" for $sockaddr and 0 for
1956 $sockaddr_maxlen.
1957
1958 The main reasons to use this syscall rather than portable accept(2)
1959 are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags
1960 and you can accept name-less sockets by specifying 0 for
1961 $sockaddr_maxlen, which is sadly not possible with perl's interface
1962 to "accept".
1865 1963
1866 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags 1964 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
1867 Calls the GNU/Linux splice(2) syscall, if available. If $r_off or 1965 Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
1868 $w_off are "undef", then "NULL" is passed for these, otherwise they 1966 $w_off are "undef", then "NULL" is passed for these, otherwise they
1869 should be the file offset. 1967 should be the file offset.
… …
1910 Example: create a pipe race-free w.r.t. threads and fork: 2008 Example: create a pipe race-free w.r.t. threads and fork:
1911 2009
1912 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC 2010 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
1913 or die "pipe2: $!\n"; 2011 or die "pipe2: $!\n";
1914 2012
2013 $fh = IO::AIO::memfd_create $pathname[, $flags]
2014 This is a direct interface to the Linux memfd_create(2) system call.
2015 The (unhelpful) default for $flags is 0, but your default should be
2016 "IO::AIO::MFD_CLOEXEC".
2017
2018 On success, the new memfd filehandle is returned, otherwise returns
2019 "undef". If the memfd_create syscall is missing, fails with
2020 "ENOSYS".
2021
2022 Please refer to memfd_create(2) for more info on this call.
2023
2024 The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
2025 "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
2026 "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
2027
2028 Example: create a new memfd.
2029
2030 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2031 or die "memfd_create: $!\n";
2032
2033 $fh = IO::AIO::pidfd_open $pid[, $flags]
2034 This is an interface to the Linux pidfd_open(2) system call. The
2035 default for $flags is 0.
2036
2037 On success, a new pidfd filehandle is returned (that is already set
2038 to close-on-exec), otherwise returns "undef". If the syscall is
2039 missing, fails with "ENOSYS".
2040
2041 Example: open pid 6341 as pidfd.
2042
2043 my $fh = IO::AIO::pidfd_open 6341
2044 or die "pidfd_open: $!\n";
2045
2046 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[,
2047 $flags]]
2048 This is an interface to the Linux pidfd_send_signal system call. The
2049 default for $siginfo is "undef" and the default for $flags is 0.
2050
2051 Returns the system call status. If the syscall is missing, fails
2052 with "ENOSYS".
2053
2054 When specified, $siginfo must be a reference to a hash with one or
2055 more of the following members:
2056
2057 code - the "si_code" member
2058 pid - the "si_pid" member
2059 uid - the "si_uid" member
2060 value_int - the "si_value.sival_int" member
2061 value_ptr - the "si_value.sival_ptr" member, specified as an integer
2062
2063 Example: send a SIGKILL to the specified process.
2064
2065 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2066 and die "pidfd_send_signal: $!\n";
2067
2068 Example: send a SIGKILL to the specified process with extra data.
2069
2070 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2071 and die "pidfd_send_signal: $!\n";
2072
2073 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2074 This is an interface to the Linux pidfd_getfd system call. The
2075 default for $flags is 0.
2076
2077 On success, returns a dup'ed copy of the target file descriptor
2078 (specified as an integer) returned (that is already set to
2079 close-on-exec), otherwise returns "undef". If the syscall is
2080 missing, fails with "ENOSYS".
2081
2082 Example: get a copy of standard error of another process and print
2083 soemthing to it.
2084
2085 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2086 or die "pidfd_getfd: $!\n";
2087 print $errfh "stderr\n";
2088
1915 $fh = IO::AIO::eventfd [$initval, [$flags]] 2089 $fh = IO::AIO::eventfd [$initval, [$flags]]
1916 This is a direct interface to the Linux eventfd(2) system call. The 2090 This is a direct interface to the Linux eventfd(2) system call. The
1917 (unhelpful) defaults for $initval and $flags are 0 for both. 2091 (unhelpful) defaults for $initval and $flags are 0 for both.
1918 2092
1919 On success, the new eventfd filehandle is returned, otherwise 2093 On success, the new eventfd filehandle is returned, otherwise
… …
1926 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and 2100 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
1927 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30). 2101 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
1928 2102
1929 Example: create a new eventfd filehandle: 2103 Example: create a new eventfd filehandle:
1930 2104
1931 $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC 2105 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
1932 or die "eventfd: $!\n"; 2106 or die "eventfd: $!\n";
1933 2107
1934 $fh = IO::AIO::timerfd_create $clockid[, $flags] 2108 $fh = IO::AIO::timerfd_create $clockid[, $flags]
1935 This is a direct interface to the Linux timerfd_create(2) system 2109 This is a direct interface to the Linux timerfd_create(2) system
1936 call. The (unhelpful) default for $flags is 0. 2110 call. The (unhelpful) default for $flags is 0, but your default
2111 should be "IO::AIO::TFD_CLOEXEC".
1937 2112
1938 On success, the new timerfd filehandle is returned, otherwise 2113 On success, the new timerfd filehandle is returned, otherwise
1939 returns "undef". If the eventfd syscall is missing, fails with 2114 returns "undef". If the timerfd_create syscall is missing, fails
1940 "ENOSYS". 2115 with "ENOSYS".
1941 2116
1942 Please refer to timerfd_create(2) for more info on this call. 2117 Please refer to timerfd_create(2) for more info on this call.
1943 2118
1944 The following $clockid values are available: 2119 The following $clockid values are available:
1945 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC" 2120 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
… …
2088 I am not sure anything can be done about this, so this is considered a 2263 I am not sure anything can be done about this, so this is considered a
2089 known issue, rather than a bug. 2264 known issue, rather than a bug.
2090 2265
2091SEE ALSO 2266SEE ALSO
2092 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a 2267 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
2093 more natural syntax. 2268 more natural syntax and IO::FDPass for file descriptor passing.
2094 2269
2095AUTHOR 2270AUTHOR
2096 Marc Lehmann <schmorp@schmorp.de> 2271 Marc Lehmann <schmorp@schmorp.de>
2097 http://home.schmorp.de/ 2272 http://home.schmorp.de/
2098 2273

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines