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.69 by root, Tue Sep 6 10:56:12 2022 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
… …
887 So in general, you should only use these calls for things that do 921 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 922 (filesystem) I/O, not for things that wait for other events
889 (network, other processes), although if you are careful and know 923 (network, other processes), although if you are careful and know
890 what you are doing, you still can. 924 what you are doing, you still can.
891 925
892 The following constants are available (missing ones are, as usual 926 The following constants are available and can be used for normal
893 0): 927 "ioctl" and "fcntl" as well (missing ones are, as usual 0):
894 928
895 "F_DUPFD_CLOEXEC", 929 "F_DUPFD_CLOEXEC",
896 930
897 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW", 931 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
898 932
899 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE", 933 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
900 "FIDEDUPERANGE". 934 "FIDEDUPERANGE".
935
936 "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
937 "F_SEAL_GROW" and "F_SEAL_WRITE".
901 938
902 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION", 939 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
903 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP". 940 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
904 941
905 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR", 942 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
… …
916 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME", 953 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
917 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT", 954 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
918 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT", 955 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
919 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX", 956 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
920 "FS_XFLAG_HASATTR", 957 "FS_XFLAG_HASATTR",
958
959 "BLKROSET", "BLKROGET", "BLKRRPART", "BLKGETSIZE", "BLKFLSBUF",
960 "BLKRASET", "BLKRAGET", "BLKFRASET", "BLKFRAGET", "BLKSECTSET",
961 "BLKSECTGET", "BLKSSZGET", "BLKBSZGET", "BLKBSZSET", "BLKGETSIZE64",
921 962
922 aio_sync $callback->($status) 963 aio_sync $callback->($status)
923 Asynchronously call sync and call the callback when finished. 964 Asynchronously call sync and call the callback when finished.
924 965
925 aio_fsync $fh, $callback->($status) 966 aio_fsync $fh, $callback->($status)
… …
1016 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh; 1057 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1017 aio_mlock $data; # mlock in background 1058 aio_mlock $data; # mlock in background
1018 1059
1019 aio_mlockall $flags, $callback->($status) 1060 aio_mlockall $flags, $callback->($status)
1020 Calls the "mlockall" function with the given $flags (a combination 1061 Calls the "mlockall" function with the given $flags (a combination
1021 of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE"). 1062 of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
1063 "IO::AIO::MCL_ONFAULT").
1022 1064
1023 On systems that do not implement "mlockall", this function returns 1065 On systems that do not implement "mlockall", this function returns
1024 -1 and sets errno to "ENOSYS". 1066 -1 and sets errno to "ENOSYS". Similarly, flag combinations not
1067 supported by the system result in a return value of -1 with errno
1068 being set to "EINVAL".
1025 1069
1026 Note that the corresponding "munlockall" is synchronous and is 1070 Note that the corresponding "munlockall" is synchronous and is
1027 documented under "MISCELLANEOUS FUNCTIONS". 1071 documented under "MISCELLANEOUS FUNCTIONS".
1028 1072
1029 Example: asynchronously lock all current and future pages into 1073 Example: asynchronously lock all current and future pages into
… …
1218 fails the request with "ENOENT", there is often no need for error 1262 fails the request with "ENOENT", there is often no need for error
1219 checking in the "aio_wd" callback, as future requests using the 1263 checking in the "aio_wd" callback, as future requests using the
1220 value will fail in the expected way. 1264 value will fail in the expected way.
1221 1265
1222 IO::AIO::CWD 1266 IO::AIO::CWD
1223 This is a compiletime constant (object) that represents the process 1267 This is a compile time constant (object) that represents the process
1224 current working directory. 1268 current working directory.
1225 1269
1226 Specifying this object as working directory object for a pathname is 1270 Specifying this object as working directory object for a pathname is
1227 as if the pathname would be specified directly, without a directory 1271 as if the pathname would be specified directly, without a directory
1228 object. For example, these calls are functionally identical: 1272 object. For example, these calls are functionally identical:
… …
1562 no longer exceeded. 1606 no longer exceeded.
1563 1607
1564 In other words, this setting does not enforce a queue limit, but can 1608 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. 1609 be used to make poll functions block if the limit is exceeded.
1566 1610
1567 This is a very bad function to use in interactive programs because 1611 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 1612 blocks, and a bad way to reduce concurrency because it is inexact.
1569 inexact: Better use an "aio_group" together with a feed callback. 1613 If you need to issue many requests without being able to call a poll
1614 function on demand, it is better to use an "aio_group" together with
1615 a feed callback.
1570 1616
1571 Its main use is in scripts without an event loop - when you want to 1617 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: 1618 stat a lot of files, you can write something like this:
1573 1619
1574 IO::AIO::max_outstanding 32; 1620 IO::AIO::max_outstanding 32;
… …
1579 } 1625 }
1580 1626
1581 IO::AIO::flush; 1627 IO::AIO::flush;
1582 1628
1583 The call to "poll_cb" inside the loop will normally return 1629 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 1630 instantly, allowing the loop to progress, but as soon as more than
1585 will block until some requests have been handled. This keeps the 1631 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 1632 been handled. This keeps the loop from pushing a large number of
1587 queue. 1633 "aio_stat" requests onto the queue (which, with many paths to stat,
1634 can use up a lot of memory).
1588 1635
1589 The default value for "max_outstanding" is very large, so there is 1636 The default value for "max_outstanding" is very large, so there is
1590 no practical limit on the number of outstanding requests. 1637 no practical limit on the number of outstanding requests.
1591 1638
1592 STATISTICAL INFORMATION 1639 STATISTICAL INFORMATION
… …
1638 below, for full accuracy. 1685 below, for full accuracy.
1639 1686
1640 File birth time is only available when the OS and perl support it 1687 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 1688 (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 1689 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 1690 advantage of it). On systems where it isn't available, 0 is
1644 currently returned, but this might change to "undef" in a future 1691 currently returned, but this might change to "undef" in a future
1645 version. 1692 version.
1646 1693
1647 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime 1694 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1648 Returns access, modification, change and birth time all in one go, 1695 Returns access, modification, change and birth time all in one go,
… …
1664 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec 1711 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1665 Like the functions above, but returns all four times in one go (and 1712 Like the functions above, but returns all four times in one go (and
1666 maybe more in future versions). 1713 maybe more in future versions).
1667 1714
1668 $counter = IO::AIO::st_gen 1715 $counter = IO::AIO::st_gen
1669 Returns the generation counter of the file. This is only available 1716 Returns the generation counter (in practice this is just a random
1670 on platforms which have this member in their "struct stat" (most 1717 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 1718 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 1719 writing) and generally only to the root usert. If unsupported, 0 is
1673 "undef" in a future version. 1720 returned, but this might change to "undef" in a future version.
1674 1721
1675 Example: print the high resolution modification time of /etc, using 1722 Example: print the high resolution modification time of /etc, using
1676 "stat", and "IO::AIO::aio_stat". 1723 "stat", and "IO::AIO::aio_stat".
1677 1724
1678 if (stat "/etc") { 1725 if (stat "/etc") {
… …
1697 IO::AIO implements some functions that are useful when you want to use 1744 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 1745 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_*" 1746 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1700 counterpart. 1747 counterpart.
1701 1748
1749 $retval = IO::AIO::fexecve $fh, $argv, $envp
1750 A more-or-less direct equivalent to the POSIX "fexecve" functions,
1751 which allows you to specify the program to be executed via a file
1752 descriptor (or handle). Returns -1 and sets errno to "ENOSYS" if not
1753 available.
1754
1755 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data =
1756 undef
1757 Calls the GNU/Linux mount syscall with the given arguments. All
1758 except $flags are strings, and if $data is "undef", a "NULL" will be
1759 passed.
1760
1761 The following values for $flags are available:
1762
1763 "IO::AIO::MS_RDONLY", "IO::AIO::MS_NOSUID", "IO::AIO::MS_NODEV",
1764 "IO::AIO::MS_NOEXEC", "IO::AIO::MS_SYNCHRONOUS",
1765 "IO::AIO::MS_REMOUNT", "IO::AIO::MS_MANDLOCK",
1766 "IO::AIO::MS_DIRSYNC", "IO::AIO::MS_NOATIME",
1767 "IO::AIO::MS_NODIRATIME", "IO::AIO::MS_BIND", "IO::AIO::MS_MOVE",
1768 "IO::AIO::MS_REC", "IO::AIO::MS_SILENT", "IO::AIO::MS_POSIXACL",
1769 "IO::AIO::MS_UNBINDABLE", "IO::AIO::MS_PRIVATE",
1770 "IO::AIO::MS_SLAVE", "IO::AIO::MS_SHARED", "IO::AIO::MS_RELATIME",
1771 "IO::AIO::MS_KERNMOUNT", "IO::AIO::MS_I_VERSION",
1772 "IO::AIO::MS_STRICTATIME", "IO::AIO::MS_LAZYTIME",
1773 "IO::AIO::MS_ACTIVE", "IO::AIO::MS_NOUSER", "IO::AIO::MS_RMT_MASK",
1774 "IO::AIO::MS_MGC_VAL" and "IO::AIO::MS_MGC_MSK".
1775
1776 $retval = IO::AIO::umount $path, $flags = 0
1777 Invokes the GNU/Linux "umount" or "umount2" syscalls. Always calls
1778 "umount" if $flags is 0, otherwqise always tries to call "umount2".
1779
1780 The following $flags are available:
1781
1782 "IO::AIO::MNT_FORCE", "IO::AIO::MNT_DETACH", "IO::AIO::MNT_EXPIRE"
1783 and "IO::AIO::UMOUNT_NOFOLLOW".
1784
1702 $numfd = IO::AIO::get_fdlimit 1785 $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 1786 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 1787 "undef" and sets $! in case of an error. The limit is one larger
1707 than the highest valid file descriptor number. 1788 than the highest valid file descriptor number.
1708 1789
1709 IO::AIO::min_fdlimit [$numfd] 1790 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 1791 Try to increase the current file descriptor limit(s) to at least
1713 $numfd by changing the soft or hard file descriptor resource limit. 1792 $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 1793 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 1794 this is not recommended when you know the actual minimum that you
1716 require. 1795 require.
… …
1803 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to 1882 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1804 "MAP_ANON" if your system only provides this constant), 1883 "MAP_ANON" if your system only provides this constant),
1805 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", 1884 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1806 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", 1885 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1807 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", 1886 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1808 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or 1887 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1809 "IO::AIO::MAP_STACK". 1888 "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
1889 "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1810 1890
1811 If $fh is "undef", then a file descriptor of -1 is passed. 1891 If $fh is "undef", then a file descriptor of -1 is passed.
1812 1892
1813 $offset is the offset from the start of the file - it generally must 1893 $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. 1894 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
… …
1851 version. 1931 version.
1852 1932
1853 On systems where this call is not supported or is not emulated, this 1933 On systems where this call is not supported or is not emulated, this
1854 call returns falls and sets $! to "ENOSYS". 1934 call returns falls and sets $! to "ENOSYS".
1855 1935
1936 IO::AIO::mlockall $flags
1937 Calls the "eio_mlockall_sync" function, which is like
1938 "aio_mlockall", but is blocking.
1939
1856 IO::AIO::munlock $scalar, $offset = 0, $length = undef 1940 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1857 Calls the "munlock" function, undoing the effects of a previous 1941 Calls the "munlock" function, undoing the effects of a previous
1858 "aio_mlock" call (see its description for details). 1942 "aio_mlock" call (see its description for details).
1859 1943
1860 IO::AIO::munlockall 1944 IO::AIO::munlockall
1861 Calls the "munlockall" function. 1945 Calls the "munlockall" function.
1862 1946
1863 On systems that do not implement "munlockall", this function returns 1947 On systems that do not implement "munlockall", this function returns
1864 ENOSYS, otherwise the return value of "munlockall". 1948 ENOSYS, otherwise the return value of "munlockall".
1949
1950 $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
1951 Uses the GNU/Linux accept4(2) syscall, if available, to accept a
1952 socket and return the new file handle on success, or sets $! and
1953 returns "undef" on error.
1954
1955 The remote name of the new socket will be stored in $sockaddr, which
1956 will be extended to allow for at least $sockaddr_maxlen octets. If
1957 the socket name does not fit into $sockaddr_maxlen octets, this is
1958 signaled by returning a longer string in $sockaddr, which might or
1959 might not be truncated.
1960
1961 To accept name-less sockets, use "undef" for $sockaddr and 0 for
1962 $sockaddr_maxlen.
1963
1964 The main reasons to use this syscall rather than portable accept(2)
1965 are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags
1966 and you can accept name-less sockets by specifying 0 for
1967 $sockaddr_maxlen, which is sadly not possible with perl's interface
1968 to "accept".
1865 1969
1866 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags 1970 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 1971 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 1972 $w_off are "undef", then "NULL" is passed for these, otherwise they
1869 should be the file offset. 1973 should be the file offset.
… …
1910 Example: create a pipe race-free w.r.t. threads and fork: 2014 Example: create a pipe race-free w.r.t. threads and fork:
1911 2015
1912 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC 2016 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
1913 or die "pipe2: $!\n"; 2017 or die "pipe2: $!\n";
1914 2018
2019 $fh = IO::AIO::memfd_create $pathname[, $flags]
2020 This is a direct interface to the Linux memfd_create(2) system call.
2021 The (unhelpful) default for $flags is 0, but your default should be
2022 "IO::AIO::MFD_CLOEXEC".
2023
2024 On success, the new memfd filehandle is returned, otherwise returns
2025 "undef". If the memfd_create syscall is missing, fails with
2026 "ENOSYS".
2027
2028 Please refer to memfd_create(2) for more info on this call.
2029
2030 The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
2031 "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
2032 "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
2033
2034 Example: create a new memfd.
2035
2036 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2037 or die "memfd_create: $!\n";
2038
2039 $fh = IO::AIO::pidfd_open $pid[, $flags]
2040 This is an interface to the Linux pidfd_open(2) system call. The
2041 default for $flags is 0.
2042
2043 On success, a new pidfd filehandle is returned (that is already set
2044 to close-on-exec), otherwise returns "undef". If the syscall is
2045 missing, fails with "ENOSYS".
2046
2047 Example: open pid 6341 as pidfd.
2048
2049 my $fh = IO::AIO::pidfd_open 6341
2050 or die "pidfd_open: $!\n";
2051
2052 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[,
2053 $flags]]
2054 This is an interface to the Linux pidfd_send_signal system call. The
2055 default for $siginfo is "undef" and the default for $flags is 0.
2056
2057 Returns the system call status. If the syscall is missing, fails
2058 with "ENOSYS".
2059
2060 When specified, $siginfo must be a reference to a hash with one or
2061 more of the following members:
2062
2063 code - the "si_code" member
2064 pid - the "si_pid" member
2065 uid - the "si_uid" member
2066 value_int - the "si_value.sival_int" member
2067 value_ptr - the "si_value.sival_ptr" member, specified as an integer
2068
2069 Example: send a SIGKILL to the specified process.
2070
2071 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2072 and die "pidfd_send_signal: $!\n";
2073
2074 Example: send a SIGKILL to the specified process with extra data.
2075
2076 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2077 and die "pidfd_send_signal: $!\n";
2078
2079 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2080 This is an interface to the Linux pidfd_getfd system call. The
2081 default for $flags is 0.
2082
2083 On success, returns a dup'ed copy of the target file descriptor
2084 (specified as an integer) returned (that is already set to
2085 close-on-exec), otherwise returns "undef". If the syscall is
2086 missing, fails with "ENOSYS".
2087
2088 Example: get a copy of standard error of another process and print
2089 soemthing to it.
2090
2091 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2092 or die "pidfd_getfd: $!\n";
2093 print $errfh "stderr\n";
2094
1915 $fh = IO::AIO::eventfd [$initval, [$flags]] 2095 $fh = IO::AIO::eventfd [$initval, [$flags]]
1916 This is a direct interface to the Linux eventfd(2) system call. The 2096 This is a direct interface to the Linux eventfd(2) system call. The
1917 (unhelpful) defaults for $initval and $flags are 0 for both. 2097 (unhelpful) defaults for $initval and $flags are 0 for both.
1918 2098
1919 On success, the new eventfd filehandle is returned, otherwise 2099 On success, the new eventfd filehandle is returned, otherwise
… …
1926 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and 2106 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
1927 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30). 2107 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
1928 2108
1929 Example: create a new eventfd filehandle: 2109 Example: create a new eventfd filehandle:
1930 2110
1931 $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC 2111 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
1932 or die "eventfd: $!\n"; 2112 or die "eventfd: $!\n";
1933 2113
1934 $fh = IO::AIO::timerfd_create $clockid[, $flags] 2114 $fh = IO::AIO::timerfd_create $clockid[, $flags]
1935 This is a direct interface to the Linux timerfd_create(2) system 2115 This is a direct interface to the Linux timerfd_create(2) system
1936 call. The (unhelpful) default for $flags is 0. 2116 call. The (unhelpful) default for $flags is 0, but your default
2117 should be "IO::AIO::TFD_CLOEXEC".
1937 2118
1938 On success, the new timerfd filehandle is returned, otherwise 2119 On success, the new timerfd filehandle is returned, otherwise
1939 returns "undef". If the eventfd syscall is missing, fails with 2120 returns "undef". If the timerfd_create syscall is missing, fails
1940 "ENOSYS". 2121 with "ENOSYS".
1941 2122
1942 Please refer to timerfd_create(2) for more info on this call. 2123 Please refer to timerfd_create(2) for more info on this call.
1943 2124
1944 The following $clockid values are available: 2125 The following $clockid values are available:
1945 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC" 2126 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
… …
2088 I am not sure anything can be done about this, so this is considered a 2269 I am not sure anything can be done about this, so this is considered a
2089 known issue, rather than a bug. 2270 known issue, rather than a bug.
2090 2271
2091SEE ALSO 2272SEE ALSO
2092 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a 2273 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
2093 more natural syntax. 2274 more natural syntax and IO::FDPass for file descriptor passing.
2094 2275
2095AUTHOR 2276AUTHOR
2096 Marc Lehmann <schmorp@schmorp.de> 2277 Marc Lehmann <schmorp@schmorp.de>
2097 http://home.schmorp.de/ 2278 http://home.schmorp.de/
2098 2279

Diff Legend

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