Linux APIs

(5 intermediate revisions by the same user not shown)

Line 1:

The Linux kernel is a protean, rapidly-changing thing. This is reflected even in "stable" APIs, especially when additions are strictly augmentative with regards to standards. Readers of classics like [[APIUE]] would do well to keep up with their [[LKML]], or at least man pages. I'm documenting departures from these standards as I come across them in various man pages and source code. The kernel man pages can be browsed at http://www.kernel.org/doc/man-pages/online_pages.html. This page serves as a companion to "[[FreeBSD APIs]]".

The Linux kernel is a protean, rapidly-changing thing. This is reflected even in "stable" APIs, especially when additions are strictly augmentative with regards to standards. Readers of classics like [[APIUE]] would do well to keep up with their [[LKML]], or at least man pages. I'm documenting departures from these standards as I come across them in various man pages and source code. The kernel man pages can be browsed at http://www.kernel.org/doc/man-pages/online_pages.html. This page serves as a companion to "[[FreeBSD APIs]]" and "[[POSIX]]".

== File descriptors ==

* Since 2.1.69 and glibc 2.1, <tt>pread(2)</tt> and <tt>pwrite(2)</tt> have allowed <tt>read(2)</tt>- and <tt>write(2)</tt>-like behavior on a file descriptor from a specified offset, without updating the offset. This allows for the atomic equivalent of an <tt>lseek(2)</tt> and an I/O, particularly useful when multiple threads are working with the same file descriptor (since file descriptor offset is shared across the process).

* Since 2.6.16, the <tt>openat(2)</tt> system call can <tt>open(2)</tt> a file relative to an open directory provided as the first argument. As the man page says:

~~<pre> openat() and other similar system calls suffixed "at" are supported for~~

~~two reasons.~~

~~First, openat() allows an application to avoid race conditions that~~

~~could occur when using open(2) to open files in directories other than~~

~~the current working directory. These race conditions result from the~~

~~fact that some component of the directory prefix given to open(2) could~~

~~be changed in parallel with the call to open(2). Such races can be~~

~~avoided by opening a file descriptor for the target directory, and then~~

~~specifying that file descriptor as the dirfd argument of openat().~~

~~Second, openat() allows the implementation of a per-thread "current~~

~~working directory", via file descriptor(s) maintained by the applica‐~~

~~tion. (This functionality can also be obtained by tricks based on the~~

~~use of /proc/self/fd/dirfd, but less efficiently.)</pre>~~

* Since 2.6.23, the <tt>open(2)</tt> system call accepts the <tt>O_CLOEXEC</tt> flag (as does <tt>recvmsg(2)</tt> and the corresponding <tt>MSG_CMSG_CLOEXEC</tt> flag). This atomically sets the close-on-exec flag upon update of the dtable, protecting against a race condition arising from <tt>fork(2)</tt>+<tt>exec(2)</tt> calls in other threads.

** Since 2.6.24, <tt>fcntl(2)</tt> implements a <tt>F_DUPFD_CLOEXEC</tt> operation, mating <tt>O_CLOEXEC</tt> to <tt>F_DUPFD</tt>.

Line 27:

Line 11:

* The obsolete BSD implementation of [[asynchronous I/O]] is extended via the <tt>F_GETSIG</tt> and <tt>F_SETSIG</tt> subcommands to <tt>fcntl(2)</tt>.

* Since 2.6.22, the <tt>eventfd(2)</tt> system call returns a file descriptor that can be used for userspace and kernel to userspace event notification. It is associated with an 8-byte kernelspace counter, which the first parameter initializes. Since Linux 2.6.27, <tt>eventfd2(2)</tt> system call also accepts a ''flags'' parameter, specified using <tt>EFD_NONBLOCK</tt> and <tt>EFD_CLOEXEC</tt>. Support for <tt>eventfd(2)</tt> was added in [[Glibc|glibc]] 2.8, and transparent support for <tt>eventfd2(2)</tt> was added in [[Glibc|glibc]] 2.9.

* 2.6.39 introduced <tt>name_to_handle_at()</tt> and <tt>open_by_handle_at()</tt>, similar to FreeBSD's <tt>getfh()</tt> and <tt>openfh()</tt>. They effectively break <tt>openat()</tt> into two parts.

* Since 6.10, <tt>fcntl(2)</tt> supports <tt>F_DUPFD_QUERY</tt> to test whether two file descriptors reference the same underlying file.

==Synchronization==

Line 34:

Line 20:

* <tt>arch_prctl(2)</tt> address architecture-specific <tt>prctl(2)</tt>-like features. It needn't generally be used. [[libc|glibc]] provides no prototype for <tt>arch_prctl(2)</tt>.

** On x86-64, it supports setting and retrieving the value of the FS and GS registers.

* <tt>kcmp(2)</tt> was added in 3.5 (when built with <tt>CONFIG_CHECKPOINT_RESTORE</tt>) to test whether two resources of two (possibly distinct) processes are equal. Since 5.12, this can be enabled with <tt>CONFIG_KCMP</tt>.

===Execution resources===

General details of cpu partitioning and affinity can be found on the [[cpuset]] page.

Line 98:

Line 85:

* <tt>process_vm_readv(2)</tt> allows a process to directly read from another process's address space, while <tt>process_vm_writev(2)</tt> allows one process to write into another's. Both were introduced in 3.5, and require the CROSS_MEMORY_ATTACH kernel option.

==Mounts==

6.8 introduced <tt>listmount</tt> and <tt>statmount</tt>.

==Devices==

===Ethtool===

* The <tt>SIOCETHTOOL</tt> ioctl supports low-level operations on supported networking devices. It exchanges a <tt>struct ifreq</tt> whose <tt>ifr_data</tt> field points to some ethtool struct corresponding to a provided subcommand.

==See Also==

* "[http://lkml.indiana.edu/hypermail/linux/kernel/0503.1/2603.html Capabilities across execve(2)]" on [[LKML]] is insightful commentary on capabilities

Linux APIs: Difference between revisions

Dank (talk | contribs)

@@ Line 1: / Line 1: @@
-The Linux kernel is a protean, rapidly-changing thing. This is reflected even in "stable" APIs, especially when additions are strictly augmentative with regards to standards. Readers of classics like [[APIUE]] would do well to keep up with their [[LKML]], or at least man pages. I'm documenting departures from these standards as I come across them in various man pages and source code. The kernel man pages can be browsed at http://www.kernel.org/doc/man-pages/online_pages.html. This page serves as a companion to "[[FreeBSD APIs]]".
+The Linux kernel is a protean, rapidly-changing thing. This is reflected even in "stable" APIs, especially when additions are strictly augmentative with regards to standards. Readers of classics like [[APIUE]] would do well to keep up with their [[LKML]], or at least man pages. I'm documenting departures from these standards as I come across them in various man pages and source code. The kernel man pages can be browsed at http://www.kernel.org/doc/man-pages/online_pages.html. This page serves as a companion to "[[FreeBSD APIs]]" and "[[POSIX]]".
 == File descriptors ==
 * Since 2.1.69 and glibc 2.1, <tt>pread(2)</tt> and <tt>pwrite(2)</tt> have allowed <tt>read(2)</tt>- and <tt>write(2)</tt>-like behavior on a file descriptor from a specified offset, without updating the offset. This allows for the atomic equivalent of an <tt>lseek(2)</tt> and an I/O, particularly useful when multiple threads are working with the same file descriptor (since file descriptor offset is shared across the process).
-* Since 2.6.16, the <tt>openat(2)</tt> system call can <tt>open(2)</tt> a file relative to an open directory provided as the first argument. As the man page says:
-<pre>       openat() and other similar system calls suffixed "at" are supported for
-       two reasons.
-       First,  openat()  allows  an  application to avoid race conditions that
-       could occur when using open(2) to open files in directories other  than
-       the  current  working directory.  These race conditions result from the
-       fact that some component of the directory prefix given to open(2) could
-       be  changed  in  parallel  with the call to open(2).  Such races can be
-       avoided by opening a file descriptor for the target directory, and then
-       specifying that file descriptor as the dirfd argument of openat().
-       Second,  openat()  allows  the  implementation of a per-thread "current
-       working directory", via file descriptor(s) maintained by  the  applica‐
-       tion.   (This functionality can also be obtained by tricks based on the
-       use of /proc/self/fd/dirfd, but less efficiently.)</pre>
 * Since 2.6.23, the <tt>open(2)</tt> system call accepts the <tt>O_CLOEXEC</tt> flag (as does <tt>recvmsg(2)</tt> and the corresponding <tt>MSG_CMSG_CLOEXEC</tt> flag). This atomically sets the close-on-exec flag upon update of the dtable, protecting against a race condition arising from <tt>fork(2)</tt>+<tt>exec(2)</tt> calls in other threads.
 ** Since 2.6.24, <tt>fcntl(2)</tt> implements a <tt>F_DUPFD_CLOEXEC</tt> operation, mating <tt>O_CLOEXEC</tt> to <tt>F_DUPFD</tt>.
@@ Line 27: / Line 11: @@
 * The obsolete BSD implementation of [[asynchronous I/O]] is extended via the <tt>F_GETSIG</tt> and <tt>F_SETSIG</tt> subcommands to <tt>fcntl(2)</tt>.
 * Since 2.6.22, the <tt>eventfd(2)</tt> system call returns a file descriptor that can be used for userspace and kernel to userspace event notification. It is associated with an 8-byte kernelspace counter, which the first parameter initializes. Since Linux 2.6.27, <tt>eventfd2(2)</tt> system call also accepts a ''flags'' parameter, specified using <tt>EFD_NONBLOCK</tt> and <tt>EFD_CLOEXEC</tt>. Support for <tt>eventfd(2)</tt> was added in [[Glibc|glibc]] 2.8, and transparent support for <tt>eventfd2(2)</tt> was added in [[Glibc|glibc]] 2.9.
+* 2.6.39 introduced <tt>name_to_handle_at()</tt> and <tt>open_by_handle_at()</tt>, similar to FreeBSD's <tt>getfh()</tt> and <tt>openfh()</tt>. They effectively break <tt>openat()</tt> into two parts.
+* Since 6.10, <tt>fcntl(2)</tt> supports <tt>F_DUPFD_QUERY</tt> to test whether two file descriptors reference the same underlying file.
 ==Synchronization==
@@ Line 34: / Line 20: @@
 * <tt>arch_prctl(2)</tt> address architecture-specific <tt>prctl(2)</tt>-like features. It needn't generally be used. [[libc|glibc]] provides no prototype for <tt>arch_prctl(2)</tt>.
 ** On x86-64, it supports setting and retrieving the value of the FS and GS registers.
+* <tt>kcmp(2)</tt> was added in 3.5 (when built with <tt>CONFIG_CHECKPOINT_RESTORE</tt>) to test whether two resources of two (possibly distinct) processes are equal. Since 5.12, this can be enabled with <tt>CONFIG_KCMP</tt>.
 ===Execution resources===
 General details of cpu partitioning and affinity can be found on the [[cpuset]] page.
@@ Line 98: / Line 85: @@
 * <tt>process_vm_readv(2)</tt> allows a process to directly read from another process's address space, while <tt>process_vm_writev(2)</tt> allows one process to write into another's. Both were introduced in 3.5, and require the CROSS_MEMORY_ATTACH kernel option.
+==Mounts==
+.8 introduced <tt>listmount</tt> and <tt>statmount</tt>.
 ==Devices==
 ===Ethtool===
 * The <tt>SIOCETHTOOL</tt> ioctl supports low-level operations on supported networking devices. It exchanges a <tt>struct ifreq</tt> whose <tt>ifr_data</tt> field points to some ethtool struct corresponding to a provided subcommand.
 ==See Also==
 * "[http://lkml.indiana.edu/hypermail/linux/kernel/0503.1/2603.html Capabilities across execve(2)]" on [[LKML]] is insightful commentary on capabilities