Linux APIs

(29 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.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 10:

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==

* Since 2.5.7, [[Futexes|futexes]] have provided Linux's primary userspace locking primitive, and been at the heart of [[NPTL]]. Their API changed numerous times through 2.5's development.

== Processes ==

* <tt>prctl(2)</tt> was added to Linux 2.1.57 as an "<tt>ioctl(2)</tt> for processes". It has any number of capabilities (list them '''FIXME''').

* <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.

* <tt>getcpu(2)</tt> was added in 2.6.19, with [[libc|glibc]] support in 2.6. It identifies the current CPU and [[NUMA]] node of the thread (this might be immediately invalidated). Only one CPU and [[NUMA]] id can be reported, which might not make sense for all process models (especially the NUMA part). <tt>sched_getcpu(2)</tt> is equivalent to calling <tt>getcpu(&aid,NULL,NULL)</tt>.

* Since 2.5.8, <tt>sched_getaffinity(2)</tt> and <tt>sched_setaffinity(2)</tt> have provided affinity mask management within the process's cpuset. [[libc|Glibc]] support was added in 2.3. In [[libc|glibc]] 2.3.4's [[pthreads]] implementation, <tt>pthread_getaffinity_np(3)</tt> and <tt>pthread_setaffinity_np(3)</tt> were added as wrappers around these system calls.

* Since 2.6.26, <tt>getrusage(2)</tt> with a <tt>RUSAGE_THREAD</tt> parameter retrieves statistics for the calling thread only.

* <tt>modify_ldt(2)</tt>, specific to the x86 architecture, allows the Local Descriptor Table to be modified.

* <tt>set_thread_area(2)</tt> allows an area of memory to be designated [[Pthreads|thread-specific data]]. It was introduced in the 2.5.29 kernel.

=== clone(2) ===

* <tt>clone(2)</tt> is far more granular with regards to what's copied and shared that <tt>fork(2)</tt>.

** ...

=== POSIX capabilities ===

* CONFIG_SECURITY_CAPABILITIES must be set. ~~This page is excellent:~~ [http://www.friedhoff.org/posixfilecaps.html ~~Chris Friedhoff's~~ POSIXFileCaps page].

* CONFIG_SECURITY_CAPABILITIES must be set. Chris Friedhoff's [http://www.friedhoff.org/posixfilecaps.html POSIXFileCaps page] is excellent.

* Since 2.2.18, the <tt>prctl(2)</tt> system call accepts the PR_SET_KEEPCAPS flag, allowing capabilities to be maintained across an event causing all of effective, real and saved-set-user UIDs to become non-zero, when at least one was previously zero. This can be used together with <tt>cap_set_proc(2)</tt> for a program run as root due to need for some capability (say, CAP_NET_RAW) to drop root privileges and most capabilities.

* Since 2.6.24 or 2.6.19-rc5-mm2, CONFIG_SECURITY_FILE_CAPABILITIES enables association of POSIX capabilities with filenames via the <tt>setcap(1)</tt> tool.

Line 29:

Line 43:

== Monitoring ==

===dnotify===

* Dnotify is deprecated and terrible. Eschew it! (see the <tt>fcntl(2)</tt> man page, F_NOTIFY)

* Sexy, sexy <tt>inotify(7)</tt> has replaced it as of 2.6.13 ([[glibc]] 2.4). (Here's a useful [http://inotify.aiken.cz/?section=inotify&page=faq&lang=en FAQ]).

===inotify===

* Sexy, sexy <tt>inotify(7)</tt> has replaced dnotify as of 2.6.13 ([[glibc]] 2.4). (Here's a useful [http://inotify.aiken.cz/?section=inotify&page=faq&lang=en FAQ]).

** [[FreeBSD]] looks like it'll be emulating inotify, likely using [[kqueue|EVFILT_VNODE]].

* <tt>inotify_init(void)</tt>, since 2.6.13, creates an inotify file descriptor

* <tt>inotify_init1(int flags)</tt>, since 2.6.27, creates an inotify file descriptor. Pass <tt>IN_NONBLOCK</tt> for a nonblocking descriptor, and <tt>IN_CLOEXEC</tt> for a close-on-exec descriptor.

===fanotify===

Merged in 2.6.36.

== Netlink ==

==Networking==

See [[Linux APIs#Ethtool|below]] for ethtool (SIOCETHTOOL) coverage.

* <tt>recvmmsg(2)</tt>, added in 2.6.32 and [[glibc]] 2.12, allows multiple messages to be received from a socket, with a timeout, using a single system call.

** The new flag <tt>MSG_WAITFORONE</tt> enables <tt>MSG_DONTWAIT</tt> following receipt of the first message.

* <tt>sendmmsg(2)</tt>, added in 3.0 and [[glibc]] 2.14, allows multiple messages to be sent on a socket using a single system call.

=== Netlink ===

* Kernel 2.1 introduced the Linux [[netlink]] system and the PF_NETLINK <tt>socket(2)</tt> protocol family.

=== Socket Options ===

====SOL_SOCKET====

* SO_DOMAIN (since 2.6.32) retrieves the socket domain as an integer (eg AF_INET, AF_INET6). This is a readonly sockopt.

* SO_PROTOCOL (since 2.6.32) retrieves the socket protocol as an integer (eg IPPROTO_TCP, IPPROTO_SCTP). This is a readonly sockopt.

* SO_RCVBUFFORCE (since 2.6.14) allows processes with CAP_NET_ADMIN [[Linux APIs#POSIX Capabilities|capabilities]] to perform a <tt>SO_RCVBUF</tt> operation which overrides the <tt>rmem_max</tt> [[proc]] limit.

** Likewise, SO_SNDBUFFORCE (also since 2.6.14) allows <tt>SO_SNDBUF</tt> to override the <tt>wmem_max</tt> [[proc]] limit.

== ~~Socket Options ==~~

==== IPPROTO_IP ====

=== ~~IPPROTO_IP~~ ===

* IP_MTU_DISCOVER modifies Path MTU discovery for the associated socket descriptor.

=== IPPROTO_TCP ===

==== IPPROTO_TCP ====

* TCP_CORK, introduced during Linux 2.2, suppresses emission of packets smaller than the MSS (through a 200ms ceiling) by coalescing writes to the socket. This can be a slight hit to latency (up through the ceiling), but can be very useful for throughput-oriented services. Clearing the flag results in queued data immediately being sent. Compare with [[FreeBSD APIs#IPPROTO_TCP|FreeBSD's]] TCP_NOPUSH.

** Only since Linux 2.5.71 can TCP_CORK be combined with [[TCP|TCP_NODELAY]].

* TCP_DEFER_ACCEPT, introduced during Linux 2.4, prevents <tt>listen(2)</tt>ing sockets from appearing ready, and <tt>accept(2)</tt> from passing back descriptors, until data has been received into socket memory. Compare with [[FreeBSD APIs#SOL_SOCKET|FreeBSD's]] SO_ACCEPTFILTER.

====ICMP_FILTER====

Used only with SOCK_RAW sockets bound to the IPPROTO_ICMP protocol. The value is a bitmask of ICMP types to filter out.

== Memory ==

Line 50:

Line 83:

* The <tt>hugetlbfs</tt> file system supports [http://www.mjmwired.net/kernel/Documentation/vm/hugetlbpage.txt reduction of mapping granularity] in the VM. It's used by (among other applications) [http://www.cyberciti.biz/tips/linux-hugetlbfs-and-mysql-performance.html MySQL] and [[kvm]]. More details are available at [[Pages]].

** The <tt>*_largepages(2)/*_hugepages(2)</tt> calls were present only in Linux 2.5.36-2.5.54.

* <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.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 10: / 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==
 * Since 2.5.7, [[Futexes|futexes]] have provided Linux's primary userspace locking primitive, and been at the heart of [[NPTL]]. Their API changed numerous times through 2.5's development.
 == Processes ==
+* <tt>prctl(2)</tt> was added to Linux 2.1.57 as an "<tt>ioctl(2)</tt> for processes". It has any number of capabilities (list them '''FIXME''').
+* <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.
+* <tt>getcpu(2)</tt> was added in 2.6.19, with [[libc|glibc]] support in 2.6. It identifies the current CPU and [[NUMA]] node of the thread (this might be immediately invalidated). Only one CPU and [[NUMA]] id can be reported, which might not make sense for all process models (especially the NUMA part). <tt>sched_getcpu(2)</tt> is equivalent to calling <tt>getcpu(&aid,NULL,NULL)</tt>.
+* Since 2.5.8, <tt>sched_getaffinity(2)</tt> and <tt>sched_setaffinity(2)</tt> have provided affinity mask management within the process's cpuset. [[libc|Glibc]] support was added in 2.3. In [[libc|glibc]] 2.3.4's [[pthreads]] implementation, <tt>pthread_getaffinity_np(3)</tt> and <tt>pthread_setaffinity_np(3)</tt> were added as wrappers around these system calls.
+* Since 2.6.26, <tt>getrusage(2)</tt> with a <tt>RUSAGE_THREAD</tt> parameter retrieves statistics for the calling thread only.
+* <tt>modify_ldt(2)</tt>, specific to the x86 architecture, allows the Local Descriptor Table to be modified.
+* <tt>set_thread_area(2)</tt> allows an area of memory to be designated [[Pthreads|thread-specific data]]. It was introduced in the 2.5.29 kernel.
 === clone(2) ===
 * <tt>clone(2)</tt> is far more granular with regards to what's copied and shared that <tt>fork(2)</tt>.
 ** ...
 === POSIX capabilities ===
-* CONFIG_SECURITY_CAPABILITIES must be set. This page is excellent: [http://www.friedhoff.org/posixfilecaps.html Chris Friedhoff's POSIXFileCaps page].
+* CONFIG_SECURITY_CAPABILITIES must be set. Chris Friedhoff's [http://www.friedhoff.org/posixfilecaps.html POSIXFileCaps page] is excellent.
 * Since 2.2.18, the <tt>prctl(2)</tt> system call accepts the PR_SET_KEEPCAPS flag, allowing capabilities to be maintained across an event causing all of effective, real and saved-set-user UIDs to become non-zero, when at least one was previously zero. This can be used together with <tt>cap_set_proc(2)</tt> for a program run as root due to need for some capability (say, CAP_NET_RAW) to drop root privileges and most capabilities.
 * Since 2.6.24 or 2.6.19-rc5-mm2, CONFIG_SECURITY_FILE_CAPABILITIES enables association of POSIX capabilities with filenames via the <tt>setcap(1)</tt> tool.
@@ Line 29: / Line 43: @@
 == Monitoring ==
+===dnotify===
 * Dnotify is deprecated and terrible. Eschew it! (see the <tt>fcntl(2)</tt> man page, F_NOTIFY)
-* Sexy, sexy <tt>inotify(7)</tt> has replaced it as of 2.6.13 ([[glibc]] 2.4). (Here's a useful [http://inotify.aiken.cz/?section=inotify&page=faq&lang=en FAQ]).
+===inotify===
+* Sexy, sexy <tt>inotify(7)</tt> has replaced dnotify as of 2.6.13 ([[glibc]] 2.4). (Here's a useful [http://inotify.aiken.cz/?section=inotify&page=faq&lang=en FAQ]).
 ** [[FreeBSD]] looks like it'll be emulating inotify, likely using [[kqueue|EVFILT_VNODE]].
+* <tt>inotify_init(void)</tt>, since 2.6.13, creates an inotify file descriptor
+* <tt>inotify_init1(int flags)</tt>, since 2.6.27, creates an inotify file descriptor. Pass <tt>IN_NONBLOCK</tt> for a nonblocking descriptor, and <tt>IN_CLOEXEC</tt> for a close-on-exec descriptor.
+===fanotify===
+Merged in 2.6.36.
-== Netlink ==
+==Networking==
+See [[Linux APIs#Ethtool|below]] for ethtool (SIOCETHTOOL) coverage.
+* <tt>recvmmsg(2)</tt>, added in 2.6.32 and [[glibc]] 2.12, allows multiple messages to be received from a socket, with a timeout, using a single system call.
+** The new flag <tt>MSG_WAITFORONE</tt> enables <tt>MSG_DONTWAIT</tt> following receipt of the first message.
+* <tt>sendmmsg(2)</tt>, added in 3.0 and [[glibc]] 2.14, allows multiple messages to be sent on a socket using a single system call.
+=== Netlink ===
 * Kernel 2.1 introduced the Linux [[netlink]] system and the PF_NETLINK <tt>socket(2)</tt> protocol family.
+=== Socket Options ===
+====SOL_SOCKET====
+* SO_DOMAIN (since 2.6.32) retrieves the socket domain as an integer (eg AF_INET, AF_INET6). This is a readonly sockopt.
+* SO_PROTOCOL (since 2.6.32) retrieves the socket protocol as an integer (eg IPPROTO_TCP, IPPROTO_SCTP). This is a readonly sockopt.
+* SO_RCVBUFFORCE (since 2.6.14) allows processes with CAP_NET_ADMIN [[Linux APIs#POSIX Capabilities|capabilities]] to perform a <tt>SO_RCVBUF</tt> operation which overrides the <tt>rmem_max</tt> [[proc]] limit.
+** Likewise, SO_SNDBUFFORCE (also since 2.6.14) allows <tt>SO_SNDBUF</tt> to override the <tt>wmem_max</tt> [[proc]] limit.
-== Socket Options ==
+==== IPPROTO_IP ====
-=== IPPROTO_IP ===
 * IP_MTU_DISCOVER modifies Path MTU discovery for the associated socket descriptor.
-=== IPPROTO_TCP ===
+==== IPPROTO_TCP ====
 * TCP_CORK, introduced during Linux 2.2, suppresses emission of packets smaller than the MSS (through a 200ms ceiling) by coalescing writes to the socket. This can be a slight hit to latency (up through the ceiling), but can be very useful for throughput-oriented services. Clearing the flag results in queued data immediately being sent. Compare with [[FreeBSD APIs#IPPROTO_TCP|FreeBSD's]] TCP_NOPUSH.
 ** Only since Linux 2.5.71 can TCP_CORK be combined with [[TCP|TCP_NODELAY]].
 * TCP_DEFER_ACCEPT, introduced during Linux 2.4, prevents <tt>listen(2)</tt>ing sockets from appearing ready, and <tt>accept(2)</tt> from passing back descriptors, until data has been received into socket memory. Compare with [[FreeBSD APIs#SOL_SOCKET|FreeBSD's]] SO_ACCEPTFILTER.
+====ICMP_FILTER====
+Used only with SOCK_RAW sockets bound to the IPPROTO_ICMP protocol. The value is a bitmask of ICMP types to filter out.
 == Memory ==
@@ Line 50: / Line 83: @@
 * The <tt>hugetlbfs</tt> file system supports [http://www.mjmwired.net/kernel/Documentation/vm/hugetlbpage.txt reduction of mapping granularity] in the VM. It's used by (among other applications) [http://www.cyberciti.biz/tips/linux-hugetlbfs-and-mysql-performance.html MySQL] and [[kvm]]. More details are available at [[Pages]].
 ** The <tt>*_largepages(2)/*_hugepages(2)</tt> calls were present only in Linux 2.5.36-2.5.54.
+* <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