packet

title: packet(7)

summary: packet interface on device level

text:
# packet(7)

## NAME
packet - packet interface on device level

## SYNOPSIS

```
#include <sys/socket.h>
#include <linux/if_packet.h>
#include <net/ethernet.h> /* the L2 protocols */
```

```
packet_socket = socket(AF_PACKET, int socket_type, int protocol);
```

## DESCRIPTION
Packet sockets are used to receive or send raw packets at the device driver (OSI Layer 2) level. They allow the user to implement protocol modules in user space on top of the physical layer.

The socket_type is either SOCK_RAW for raw packets including the link-level header or SOCK_DGRAM for cooked packets with the link-level header removed. The link-level header information is available in a common format in a sockaddr_ll structure. protocol is the IEEE 802.3 protocol number in network byte order. See the <linux/if_ether.h> include file for a list of allowed protocols. When protocol is set to htons(ETH_P_ALL), then all protocols are received. All incoming packets of that protocol type will be passed to the packet socket before they are passed to the protocols implemented in the kernel. If protocol is set to zero, no packets are received. bind(2) can optionally be called with a nonzero sll_protocol to start receiving packets for the protocols specified.

In order to create a packet socket, a process must have the CAP_NET_RAW capability in the user namespace that governs its network namespace.

SOCK_RAW packets are passed to and from the device driver without any changes in the packet data. When receiving a packet, the address is still parsed and passed in a standard sockaddr_ll address structure. When transmitting a packet, the user-supplied buffer should contain the physical-layer header. That packet is then queued unmodified to the network driver of the interface defined by the destination address. Some device drivers always add other headers. SOCK_RAW is similar to but not compatible with the obsolete AF_INET/SOCK_PACKET of Linux 2.0.

SOCK_DGRAM operates on a slightly higher level. The physical header is removed before the packet is passed to the user. Packets sent through a SOCK_DGRAM packet socket get a suitable physical-layer header based on the information in the sockaddr_ll destination address before they are queued.

By default, all packets of the specified protocol type are passed to a packet socket. To get packets only from a specific interface use bind(2) specifying an address in a struct sockaddr_ll to bind the packet socket to an interface. Fields used for binding are sll_family (should be AF_PACKET), sll_protocol, and sll_ifindex.

The connect(2) operation is not supported on packet sockets.

When the MSG_TRUNC flag is passed to recvmsg(2), recv(2), or recvfrom(2), the real length of the packet on the wire is always returned, even when it is longer than the buffer.

### Address types
The sockaddr_ll structure is a device-independent physical-layer address.

```
struct sockaddr_ll {

    unsigned short sll_family;   /* Always AF_PACKET */

    unsigned short sll_protocol; /* Physical-layer protocol */

    int            sll_ifindex;  /* Interface number */

    unsigned short sll_hatype;   /* ARP hardware type */

    unsigned char  sll_pkttype;  /* Packet type */

    unsigned char  sll_halen;    /* Length of address */

    unsigned char  sll_addr[8];  /* Physical-layer address */
};
```

The fields of this structure are as follows:

sll_protocol

is the standard ethernet protocol type in network byte order as defined in the <linux/if_ether.h> include file. It defaults to the socket's protocol.

sll_ifindex

is the interface index of the interface (see netdevice(7)); 0 matches any interface (only permitted for binding). sll_hatype is an ARP type as defined in the <linux/if_arp.h> include file.

sll_pkttype

contains the packet type. Valid types are PACKET_HOST for a packet addressed to the local host, PACKET_BROADCAST for a physical-layer broadcast packet, PACKET_MULTICAST for a packet sent to a physical-layer multicast address, PACKET_OTHERHOST for a packet to some other host that has been caught by a device driver in promiscuous mode, and PACKET_OUTGOING for a packet originating from the local host that is looped back to a packet socket. These types make sense only for receiving.

sll_addr

sll_halen

contain the physical-layer (e.g., IEEE 802.3) address and its length. The exact interpretation depends on the device.

When you send packets, it is enough to specify sll_family, sll_addr, sll_halen, sll_ifindex, and sll_protocol. The other fields should be 0. sll_hatype and sll_pkttype are set on received packets for your information.

### Socket options
Packet socket options are configured by calling setsockopt(2) with level SOL_PACKET.

PACKET_ADD_MEMBERSHIP

PACKET_DROP_MEMBERSHIP

Packet sockets can be used to configure physical-layer multicasting and promiscuous mode. PACKET_ADD_MEMBERSHIP adds a binding and PACKET_DROP_MEMBERSHIP drops it. They both expect a packet_mreq structure as argument:

```
struct packet_mreq {

    int            mr_ifindex;    /* interface index */

    unsigned short mr_type;       /* action */

    unsigned short mr_alen;       /* address length */

    unsigned char  mr_address[8]; /* physical-layer address */
};

```

mr_ifindex contains the interface index for the interface whose status should be changed. The mr_type field specifies which action to perform. PACKET_MR_PROMISC enables receiving all packets on a shared medium (often known as "promiscuous mode"), PACKET_MR_MULTICAST binds the socket to the physical-layer multicast group specified in mr_address and mr_alen, and PACKET_MR_ALLMULTI sets the socket up to receive all multicast packets arriving at the interface.

In addition, the traditional ioctls SIOCSIFFLAGS, SIOCADDMULTI, SIOCDELMULTI can be used for the same purpose.

PACKET_AUXDATA (since Linux 2.6.21)

If this binary option is enabled, the packet socket passes a metadata structure along with each packet in the recvmsg(2) control field. The structure can be read with cmsg(3). It is defined as

```
struct tpacket_auxdata {

    __u32 tp_status;

    __u32 tp_len;      /* packet length */

    __u32 tp_snaplen;  /* captured length */

    __u16 tp_mac;

    __u16 tp_net;

    __u16 tp_vlan_tci;

    __u16 tp_vlan_tpid; /* Since Linux 3.14; earlier, these

                           were unused padding bytes */
};

```

PACKET_FANOUT (since Linux 3.1)

To scale processing across threads, packet sockets can form a fanout group. In this mode, each matching packet is enqueued onto only one socket in the group. A socket joins a fanout group by calling setsockopt(2) with level SOL_PACKET and option PACKET_FANOUT. Each network namespace can have up to 65536 independent groups. A socket selects a group by encoding the ID in the first 16 bits of the integer option value. The first packet socket to join a group implicitly creates it. To successfully join an existing group, subsequent packet sockets must have the same protocol, device settings, fanout mode, and flags (see below). Packet sockets can leave a fanout group only by closing the socket. The group is deleted when the last socket is closed.

Fanout supports multiple algorithms to spread traffic between sockets, as follows:

•

The default mode, PACKET_FANOUT_HASH, sends packets from the same flow to the same socket to maintain per-flow ordering. For each packet, it chooses a socket by taking the packet flow hash modulo the number of sockets in the group, where a flow hash is a hash over network-layer address and optional transport-layer port fields.

•

The load-balance mode PACKET_FANOUT_LB implements a round-robin algorithm.

•

PACKET_FANOUT_CPU selects the socket based on the CPU that the packet arrived on.

•

PACKET_FANOUT_ROLLOVER processes all data on a single socket, moving to the next when one becomes backlogged.

•

PACKET_FANOUT_RND selects the socket using a pseudo-random number generator.

•

PACKET_FANOUT_QM (available since Linux 3.14) selects the socket using the recorded queue_mapping of the received skb.

Fanout modes can take additional options. IP fragmentation causes packets from the same flow to have different flow hashes. The flag PACKET_FANOUT_FLAG_DEFRAG, if set, causes packets to be defragmented before fanout is applied, to preserve order even in this case. Fanout mode and options are communicated in the second 16 bits of the integer option value. The flag PACKET_FANOUT_FLAG_ROLLOVER enables the roll over mechanism as a backup strategy: if the original fanout algorithm selects a backlogged socket, the packet rolls over to the next available one.

PACKET_LOSS (with PACKET_TX_RING)

When a malformed packet is encountered on a transmit ring, the default is to reset its tp_status to TP_STATUS_WRONG_FORMAT and abort the transmission immediately. The malformed packet blocks itself and subsequently enqueued packets from being sent. The format error must be fixed, the associated tp_status reset to TP_STATUS_SEND_REQUEST, and the transmission process restarted via send(2). However, if PACKET_LOSS is set, any malformed packet will be skipped, its tp_status reset to TP_STATUS_AVAILABLE, and the transmission process continued.

PACKET_RESERVE (with PACKET_RX_RING)

By default, a packet receive ring writes packets immediately following the metadata structure and alignment padding. This integer option reserves additional headroom.

PACKET_RX_RING

Create a memory-mapped ring buffer for asynchronous packet reception. The packet socket reserves a contiguous region of application address space, lays it out into an array of packet slots and copies packets (up to tp_snaplen) into subsequent slots. Each packet is preceded by a metadata structure similar to tpacket_auxdata. The protocol fields encode the offset to the data from the start of the metadata header. tp_net stores the offset to the network layer. If the packet socket is of type SOCK_DGRAM, then tp_mac is the same. If it is of type SOCK_RAW, then that field stores the offset to the link-layer frame. Packet socket and application communicate the head and tail of the ring through the tp_status field. The packet socket owns all slots with tp_status equal to TP_STATUS_KERNEL. After filling a slot, it changes the status of the slot to transfer ownership to the application. During normal operation, the new tp_status value has at least the TP_STATUS_USER bit set to signal that a received packet has been stored. When the application has finished processing a packet, it transfers ownership of the slot back to the socket by setting tp_status equal to TP_STATUS_KERNEL.

Packet sockets implement multiple variants of the packet ring. The implementation details are described in Documentation/networking/packet_mmap.rst in the Linux kernel source tree.

PACKET_STATISTICS

Retrieve packet socket statistics in the form of a structure

```
struct tpacket_stats {

    unsigned int tp_packets;  /* Total packet count */

    unsigned int tp_drops;    /* Dropped packet count */
};

```

Receiving statistics resets the internal counters. The statistics structure differs when using a ring of variant TPACKET_V3.

PACKET_TIMESTAMP (with PACKET_RX_RING; since Linux 2.6.36)

The packet receive ring always stores a timestamp in the metadata header. By default, this is a software generated timestamp generated when the packet is copied into the ring. This integer option selects the type of timestamp. Besides the default, it support the two hardware formats described in Documentation/networking/timestamping.rst in the Linux kernel source tree.

PACKET_TX_RING (since Linux 2.6.31)

Create a memory-mapped ring buffer for packet transmission. This option is similar to PACKET_RX_RING and takes the same arguments. The application writes packets into slots with tp_status equal to TP_STATUS_AVAILABLE and schedules them for transmission by changing tp_status to TP_STATUS_SEND_REQUEST. When packets are ready to be transmitted, the application calls send(2) or a variant thereof. The buf and len fields of this call are ignored. If an address is passed using sendto(2) or sendmsg(2), then that overrides the socket default. On successful transmission, the socket resets tp_status to TP_STATUS_AVAILABLE. It immediately aborts the transmission on error unless PACKET_LOSS is set.

PACKET_VERSION (with PACKET_RX_RING; since Linux 2.6.27)

By default, PACKET_RX_RING creates a packet receive ring of variant TPACKET_V1. To create another variant, configure the desired variant by setting this integer option before creating the ring.

PACKET_QDISC_BYPASS (since Linux 3.14)

By default, packets sent through packet sockets pass through the kernel's qdisc (traffic control) layer, which is fine for the vast majority of use cases. For traffic generator appliances using packet sockets that intend to brute-force flood the network—for example, to test devices under load in a similar fashion to pktgen—this layer can be bypassed by setting this integer option to 1. A side effect is that packet buffering in the qdisc layer is avoided, which will lead to increased drops when network device transmit queues are busy; therefore, use at your own risk.

### Ioctls
SIOCGSTAMP can be used to receive the timestamp of the last received packet. Argument is a struct timeval variable.

In addition, all standard ioctls defined in netdevice(7) and socket(7) are valid on packet sockets.

### Error handling
Packet sockets do no error handling other than errors occurred while passing the packet to the device driver. They don't have the concept of a pending error.

## ERRORS
EADDRNOTAVAIL

Unknown multicast group address passed.

EFAULT

User passed invalid memory address.

EINVAL

Invalid argument.

EMSGSIZE

Packet is bigger than interface MTU.

ENETDOWN

Interface is not up.

ENOBUFS

Not enough memory to allocate the packet.

ENODEV

Unknown device name or interface index specified in interface address.

ENOENT

No packet received.

ENOTCONN

No interface address passed.

ENXIO

Interface address contained an invalid interface index.

EPERM

User has insufficient privileges to carry out this operation.

In addition, other errors may be generated by the low-level driver.

## VERSIONS
AF_PACKET is a new feature in Linux 2.2. Earlier Linux versions supported only SOCK_PACKET.

## NOTES
For portable programs it is suggested to use AF_PACKET via pcap(3); although this covers only a subset of the AF_PACKET features.

The SOCK_DGRAM packet sockets make no attempt to create or parse the IEEE 802.2 LLC header for a IEEE 802.3 frame. When ETH_P_802_3 is specified as protocol for sending the kernel creates the 802.3 frame and fills out the length field; the user has to supply the LLC header to get a fully conforming packet. Incoming 802.3 packets are not multiplexed on the DSAP/SSAP protocol fields; instead they are supplied to the user as protocol ETH_P_802_2 with the LLC header prefixed. It is thus not possible to bind to ETH_P_802_3; bind to ETH_P_802_2 instead and do the protocol multiplex yourself. The default for sending is the standard Ethernet DIX encapsulation with the protocol filled in.

Packet sockets are not subject to the input or output firewall chains.

### Compatibility
In Linux 2.0, the only way to get a packet socket was with the call:

```
socket(AF_INET, SOCK_PACKET, protocol)
```

This is still supported, but deprecated and strongly discouraged. The main difference between the two methods is that SOCK_PACKET uses the old struct sockaddr_pkt to specify an interface, which doesn't provide physical-layer independence.

```
struct sockaddr_pkt {

    unsigned short spkt_family;

    unsigned char  spkt_device[14];

    unsigned short spkt_protocol;
};
```

spkt_family contains the device type, spkt_protocol is the IEEE 802.3 protocol type as defined in <sys/if_ether.h> and spkt_device is the device name as a null-terminated string, for example, eth0.

This structure is obsolete and should not be used in new code.

## BUGS

### LLC header handling
The IEEE 802.2/803.3 LLC handling could be considered as a bug.

### MSG_TRUNC issues
The MSG_TRUNC recvmsg(2) extension is an ugly hack and should be replaced by a control message. There is currently no way to get the original destination address of packets via SOCK_DGRAM.

### spkt_device device name truncation
The spkt_device field of sockaddr_pkt has a size of 14 bytes, which is less than the constant IFNAMSIZ defined in <net/if.h> which is 16 bytes and describes the system limit for a network interface name. This means the names of network devices longer than 14 bytes will be truncated to fit into spkt_device. All these lengths include the terminating null byte ('\0')).

Issues from this with old code typically show up with very long interface names used by the Predictable Network Interface Names feature enabled by default in many modern Linux distributions.

The preferred solution is to rewrite code to avoid SOCK_PACKET. Possible user solutions are to disable Predictable Network Interface Names or to rename the interface to a name of at most 13 bytes, for example using the ip(8) tool.

### Documentation issues
Socket filters are not documented.

## SEE ALSO
socket(2), pcap(3), capabilities(7), ip(7), raw(7), socket(7), ip(8),

RFC 894 for the standard IP Ethernet encapsulation. RFC 1700 for the IEEE 802.3 IP encapsulation.

The <linux/if_ether.h> include file for physical-layer protocols.

The Linux kernel source tree. Documentation/networking/filter.rst describes how to apply Berkeley Packet Filters to packet sockets. tools/testing/selftests/net/psock_tpacket.c contains example source code for all available versions of PACKET_RX_RING and PACKET_TX_RING.


package: man-pages

title: path_resolution(7)

summary: how a pathname is resolved to a file

text:
# path_resolution(7)

## NAME
path_resolution - how a pathname is resolved to a file

## DESCRIPTION
Some UNIX/Linux system calls have as parameter one or more filenames. A filename (or pathname) is resolved as follows.

### Step 1: start of the resolution process
If the pathname starts with the '/' character, the starting lookup directory is the root directory of the calling process. A process inherits its root directory from its parent. Usually this will be the root directory of the file hierarchy. A process may get a different root directory by use of the chroot(2) system call, or may temporarily use a different root directory by using openat2(2) with the RESOLVE_IN_ROOT flag set.

A process may get an entirely private mount namespace in case it—or one of its ancestors—was started by an invocation of the clone(2) system call that had the CLONE_NEWNS flag set. This handles the '/' part of the pathname.

If the pathname does not start with the '/' character, the starting lookup directory of the resolution process is the current working directory of the process — or in the case of openat(2)-style system calls, the dfd argument (or the current working directory if AT_FDCWD is passed as the dfd argument). The current working directory is inherited from the parent, and can be changed by use of the chdir(2) system call.

Pathnames starting with a '/' character are called absolute pathnames. Pathnames not starting with a '/' are called relative pathnames.

### Step 2: walk along the path
Set the current lookup directory to the starting lookup directory. Now, for each nonfinal component of the pathname, where a component is a substring delimited by '/' characters, this component is looked up in the current lookup directory.

If the process does not have search permission on the current lookup directory, an EACCES error is returned ("Permission denied").

If the component is not found, an ENOENT error is returned ("No such file or directory").

If the component is found, but is neither a directory nor a symbolic link, an ENOTDIR error is returned ("Not a directory").

If the component is found and is a directory, we set the current lookup directory to that directory, and go to the next component.

If the component is found and is a symbolic link, we first resolve this symbolic link (with the current lookup directory as starting lookup directory). Upon error, that error is returned. If the result is not a directory, an ENOTDIR error is returned. If the resolution of the symbolic link is successful and returns a directory, we set the current lookup directory to that directory, and go to the next component. Note that the resolution process here can involve recursion if the prefix ('dirname') component of a pathname contains a filename that is a symbolic link that resolves to a directory (where the prefix component of that directory may contain a symbolic link, and so on). In order to protect the kernel against stack overflow, and also to protect against denial of service, there are limits on the maximum recursion depth, and on the maximum number of symbolic links followed. An ELOOP error is returned when the maximum is exceeded ("Too many levels of symbolic links").

As currently implemented on Linux, the maximum number of symbolic links that will be followed while resolving a pathname is 40. Before Linux 2.6.18, the limit on the recursion depth was 5. Starting with Linux 2.6.18, this limit was raised to 8. In Linux 4.2, the kernel's pathname-resolution code was reworked to eliminate the use of recursion, so that the only limit that remains is the maximum of 40 resolutions for the entire pathname.

The resolution of symbolic links during this stage can be blocked by using openat2(2), with the RESOLVE_NO_SYMLINKS flag set.

### Step 3: find the final entry
The lookup of the final component of the pathname goes just like that of all other components, as described in the previous step, with two differences: (i) the final component need not be a directory (at least as far as the path resolution process is concerned—it may have to be a directory, or a nondirectory, because of the requirements of the specific system call), and (ii) it is not necessarily an error if the component is not found—maybe we are just creating it. The details on the treatment of the final entry are described in the manual pages of the specific system calls.

### . and ..
By convention, every directory has the entries "." and "..", which refer to the directory itself and to its parent directory, respectively.

The path resolution process will assume that these entries have their conventional meanings, regardless of whether they are actually present in the physical filesystem.

One cannot walk up past the root: "/.." is the same as "/".

### Mount points
After a mount dev path command, the pathname "path" refers to the root of the filesystem hierarchy on the device "dev", and no longer to whatever it referred to earlier.

One can walk out of a mounted filesystem: "path/.." refers to the parent directory of "path", outside of the filesystem hierarchy on "dev".

Traversal of mount points can be blocked by using openat2(2), with the RESOLVE_NO_XDEV flag set (though note that this also restricts bind mount traversal).

### Trailing slashes
If a pathname ends in a '/', that forces resolution of the preceding component as in Step 2: the component preceding the slash either exists and resolves to a directory or it names a directory that is to be created immediately after the pathname is resolved. Otherwise, a trailing '/' is ignored.

### Final symbolic link
If the last component of a pathname is a symbolic link, then it depends on the system call whether the file referred to will be the symbolic link or the result of path resolution on its contents. For example, the system call lstat(2) will operate on the symbolic link, while stat(2) operates on the file pointed to by the symbolic link.

### Length limit
There is a maximum length for pathnames. If the pathname (or some intermediate pathname obtained while resolving symbolic links) is too long, an ENAMETOOLONG error is returned ("Filename too long").

### Empty pathname
In the original UNIX, the empty pathname referred to the current directory. Nowadays POSIX decrees that an empty pathname must not be resolved successfully. Linux returns ENOENT in this case.

### Permissions
The permission bits of a file consist of three groups of three bits; see chmod(1) and stat(2). The first group of three is used when the effective user ID of the calling process equals the owner ID of the file. The second group of three is used when the group ID of the file either equals the effective group ID of the calling process, or is one of the supplementary group IDs of the calling process (as set by setgroups(2)). When neither holds, the third group is used.

Of the three bits used, the first bit determines read permission, the second write permission, and the last execute permission in case of ordinary files, or search permission in case of directories.

Linux uses the fsuid instead of the effective user ID in permission checks. Ordinarily the fsuid will equal the effective user ID, but the fsuid can be changed by the system call setfsuid(2).

(Here "fsuid" stands for something like "filesystem user ID". The concept was required for the implementation of a user space NFS server at a time when processes could send a signal to a process with the same effective user ID. It is obsolete now. Nobody should use setfsuid(2).)

Similarly, Linux uses the fsgid ("filesystem group ID") instead of the effective group ID. See setfsgid(2).

### Bypassing permission checks: superuser and capabilities
On a traditional UNIX system, the superuser (root, user ID 0) is all-powerful, and bypasses all permissions restrictions when accessing files.

On Linux, superuser privileges are divided into capabilities (see capabilities(7)). Two capabilities are relevant for file permissions checks: CAP_DAC_OVERRIDE and CAP_DAC_READ_SEARCH. (A process has these capabilities if its fsuid is 0.)

The CAP_DAC_OVERRIDE capability overrides all permission checking, but grants execute permission only when at least one of the file's three execute permission bits is set.

The CAP_DAC_READ_SEARCH capability grants read and search permission on directories, and read permission on ordinary files.

## SEE ALSO
readlink(2), capabilities(7), credentials(7), symlink(7)


persistent-keyring

title: persistent-keyring(7)

summary: per-user persistent keyring

text:
# persistent-keyring(7)

## NAME
persistent-keyring - per-user persistent keyring

## DESCRIPTION
The persistent keyring is a keyring used to anchor keys on behalf of a user. Each UID the kernel deals with has its own persistent keyring that is shared between all threads owned by that UID. The persistent keyring has a name (description) of the form _persistent.<UID> where <UID> is the user ID of the corresponding user.

The persistent keyring may not be accessed directly, even by processes with the appropriate UID. Instead, it must first be linked to one of a process's keyrings, before that keyring can access the persistent keyring by virtue of its possessor permits. This linking is done with the keyctl_get_persistent(3) function.

If a persistent keyring does not exist when it is accessed by the keyctl_get_persistent(3) operation, it will be automatically created.

Each time the keyctl_get_persistent(3) operation is performed, the persistent keyring's expiration timer is reset to the value in:

```
/proc/sys/kernel/keys/persistent_keyring_expiry
```

Should the timeout be reached, the persistent keyring will be removed and everything it pins can then be garbage collected. The keyring will then be re-created on a subsequent call to keyctl_get_persistent(3).

The persistent keyring is not directly searched by request_key(2); it is searched only if it is linked into one of the keyrings that is searched by request_key(2).

The persistent keyring is independent of clone(2), fork(2), vfork(2), execve(2), and _exit(2). It persists until its expiration timer triggers, at which point it is garbage collected. This allows the persistent keyring to carry keys beyond the life of the kernel's record of the corresponding UID (the destruction of which results in the destruction of the user-keyring(7) and the user-session-keyring(7)). The persistent keyring can thus be used to hold authentication tokens for processes that run without user interaction, such as programs started by cron(8).

The persistent keyring is used to store UID-specific objects that themselves have limited lifetimes (e.g., kerberos tokens). If those tokens cease to be used (i.e., the persistent keyring is not accessed), then the timeout of the persistent keyring ensures that the corresponding objects are automatically discarded.

### Special operations
The keyutils library provides the keyctl_get_persistent(3) function for manipulating persistent keyrings. (This function is an interface to the keyctl(2) KEYCTL_GET_PERSISTENT operation.) This operation allows the calling thread to get the persistent keyring corresponding to its own UID or, if the thread has the CAP_SETUID capability, the persistent keyring corresponding to some other UID in the same user namespace.

## NOTES
Each user namespace owns a keyring called .persistent_register that contains links to all of the persistent keys in that namespace. (The .persistent_register keyring can be seen when reading the contents of the /proc/keys file for the UID 0 in the namespace.) The keyctl_get_persistent(3) operation looks for a key with a name of the form _persistent.UID in that keyring, creates the key if it does not exist, and links it into the keyring.

## SEE ALSO
keyctl(1), keyctl(3), keyctl_get_persistent(3), keyrings(7), process-keyring(7), session-keyring(7), thread-keyring(7), user-keyring(7), user-session-keyring(7)


title: pid_namespaces(7)

summary: overview of Linux PID namespaces

text:
# pid_namespaces(7)

## NAME
pid_namespaces - overview of Linux PID namespaces

## DESCRIPTION
For an overview of namespaces, see namespaces(7).

PID namespaces isolate the process ID number space, meaning that processes in different PID namespaces can have the same PID. PID namespaces allow containers to provide functionality such as suspending/resuming the set of processes in the container and migrating the container to a new host while the processes inside the container maintain the same PIDs.

PIDs in a new PID namespace start at 1, somewhat like a standalone system, and calls to fork(2), vfork(2), or clone(2) will produce processes with PIDs that are unique within the namespace.

Use of PID namespaces requires a kernel that is configured with the CONFIG_PID_NS option.

### The namespace init process
The first process created in a new namespace (i.e., the process created using clone(2) with the CLONE_NEWPID flag, or the first child created by a process after a call to unshare(2) using the CLONE_NEWPID flag) has the PID 1, and is the "init" process for the namespace (see init(1)). This process becomes the parent of any child processes that are orphaned because a process that resides in this PID namespace terminated (see below for further details).

If the "init" process of a PID namespace terminates, the kernel terminates all of the processes in the namespace via a SIGKILL signal. This behavior reflects the fact that the "init" process is essential for the correct operation of a PID namespace. In this case, a subsequent fork(2) into this PID namespace fail with the error ENOMEM; it is not possible to create a new process in a PID namespace whose "init" process has terminated. Such scenarios can occur when, for example, a process uses an open file descriptor for a /proc/pid/ns/pid file corresponding to a process that was in a namespace to setns(2) into that namespace after the "init" process has terminated. Another possible scenario can occur after a call to unshare(2): if the first child subsequently created by a fork(2) terminates, then subsequent calls to fork(2) fail with ENOMEM.

Only signals for which the "init" process has established a signal handler can be sent to the "init" process by other members of the PID namespace. This restriction applies even to privileged processes, and prevents other members of the PID namespace from accidentally killing the "init" process.

Likewise, a process in an ancestor namespace can—subject to the usual permission checks described in kill(2)—send signals to the "init" process of a child PID namespace only if the "init" process has established a handler for that signal. (Within the handler, the siginfo_t si_pid field described in sigaction(2) will be zero.) SIGKILL or SIGSTOP are treated exceptionally: these signals are forcibly delivered when sent from an ancestor PID namespace. Neither of these signals can be caught by the "init" process, and so will result in the usual actions associated with those signals (respectively, terminating and stopping the process).

Starting with Linux 3.4, the reboot(2) system call causes a signal to be sent to the namespace "init" process. See reboot(2) for more details.

### Nesting PID namespaces
PID namespaces can be nested: each PID namespace has a parent, except for the initial ("root") PID namespace. The parent of a PID namespace is the PID namespace of the process that created the namespace using clone(2) or unshare(2). PID namespaces thus form a tree, with all namespaces ultimately tracing their ancestry to the root namespace. Since Linux 3.7, the kernel limits the maximum nesting depth for PID namespaces to 32.

A process is visible to other processes in its PID namespace, and to the processes in each direct ancestor PID namespace going back to the root PID namespace. In this context, "visible" means that one process can be the target of operations by another process using system calls that specify a process ID. Conversely, the processes in a child PID namespace can't see processes in the parent and further removed ancestor namespaces. More succinctly: a process can see (e.g., send signals with kill(2), set nice values with setpriority(2), etc.) only processes contained in its own PID namespace and in descendants of that namespace.

A process has one process ID in each of the layers of the PID namespace hierarchy in which is visible, and walking back though each direct ancestor namespace through to the root PID namespace. System calls that operate on process IDs always operate using the process ID that is visible in the PID namespace of the caller. A call to getpid(2) always returns the PID associated with the namespace in which the process was created.

Some processes in a PID namespace may have parents that are outside of the namespace. For example, the parent of the initial process in the namespace (i.e., the init(1) process with PID 1) is necessarily in another namespace. Likewise, the direct children of a process that uses setns(2) to cause its children to join a PID namespace are in a different PID namespace from the caller of setns(2). Calls to getppid(2) for such processes return 0.

While processes may freely descend into child PID namespaces (e.g., using setns(2) with a PID namespace file descriptor), they may not move in the other direction. That is to say, processes may not enter any ancestor namespaces (parent, grandparent, etc.). Changing PID namespaces is a one-way operation.

The NS_GET_PARENT ioctl(2) operation can be used to discover the parental relationship between PID namespaces; see ioctl_ns(2).

### setns(2) and unshare(2) semantics
Calls to setns(2) that specify a PID namespace file descriptor and calls to unshare(2) with the CLONE_NEWPID flag cause children subsequently created by the caller to be placed in a different PID namespace from the caller. (Since Linux 4.12, that PID namespace is shown via the /proc/pid/ns/pid_for_children file, as described in namespaces(7).) These calls do not, however, change the PID namespace of the calling process, because doing so would change the caller's idea of its own PID (as reported by getpid()), which would break many applications and libraries.

To put things another way: a process's PID namespace membership is determined when the process is created and cannot be changed thereafter. Among other things, this means that the parental relationship between processes mirrors the parental relationship between PID namespaces: the parent of a process is either in the same namespace or resides in the immediate parent PID namespace.

A process may call unshare(2) with the CLONE_NEWPID flag only once. After it has performed this operation, its /proc/pid/ns/pid_for_children symbolic link will be empty until the first child is created in the namespace.

### Adoption of orphaned children
When a child process becomes orphaned, it is reparented to the "init" process in the PID namespace of its parent (unless one of the nearer ancestors of the parent employed the prctl(2) PR_SET_CHILD_SUBREAPER command to mark itself as the reaper of orphaned descendant processes). Note that because of the setns(2) and unshare(2) semantics described above, this may be the "init" process in the PID namespace that is the parent of the child's PID namespace, rather than the "init" process in the child's own PID namespace.

### Compatibility of CLONE_NEWPID with other CLONE_* flags
In current versions of Linux, CLONE_NEWPID can't be combined with CLONE_THREAD. Threads are required to be in the same PID namespace such that the threads in a process can send signals to each other. Similarly, it must be possible to see all of the threads of a process in the proc(5) filesystem. Additionally, if two threads were in different PID namespaces, the process ID of the process sending a signal could not be meaningfully encoded when a signal is sent (see the description of the siginfo_t type in sigaction(2)). Since this is computed when a signal is enqueued, a signal queue shared by processes in multiple PID namespaces would defeat that.

In earlier versions of Linux, CLONE_NEWPID was additionally disallowed (failing with the error EINVAL) in combination with CLONE_SIGHAND (before Linux 4.3) as well as CLONE_VM (before Linux 3.12). The changes that lifted these restrictions have also been ported to earlier stable kernels.

### /proc and PID namespaces
A /proc filesystem shows (in the /proc/pid directories) only processes visible in the PID namespace of the process that performed the mount, even if the /proc filesystem is viewed from processes in other namespaces.

After creating a new PID namespace, it is useful for the child to change its root directory and mount a new procfs instance at /proc so that tools such as ps(1) work correctly. If a new mount namespace is simultaneously created by including CLONE_NEWNS in the flags argument of clone(2) or unshare(2), then it isn't necessary to change the root directory: a new procfs instance can be mounted directly over /proc.

From a shell, the command to mount /proc is:

```
$ mount -t proc proc /proc
```

Calling readlink(2) on the path /proc/self yields the process ID of the caller in the PID namespace of the procfs mount (i.e., the PID namespace of the process that mounted the procfs). This can be useful for introspection purposes, when a process wants to discover its PID in other namespaces.

### /proc files
/proc/sys/kernel/ns_last_pid (since Linux 3.3)

This file (which is virtualized per PID namespace) displays the last PID that was allocated in this PID namespace. When the next PID is allocated, the kernel will search for the lowest unallocated PID that is greater than this value, and when this file is subsequently read it will show that PID.

This file is writable by a process that has the CAP_SYS_ADMIN or (since Linux 5.9) CAP_CHECKPOINT_RESTORE capability inside the user namespace that owns the PID namespace. This makes it possible to determine the PID that is allocated to the next process that is created inside this PID namespace.

### Miscellaneous
When a process ID is passed over a UNIX domain socket to a process in a different PID namespace (see the description of SCM_CREDENTIALS in unix(7)), it is translated into the corresponding PID value in the receiving process's PID namespace.

## STANDARDS
Linux.

## EXAMPLES
See user_namespaces(7).

## SEE ALSO
clone(2), reboot(2), setns(2), unshare(2), proc(5), capabilities(7), credentials(7), mount_namespaces(7), namespaces(7), user_namespaces(7), switch_root(8)


pipe

title: pipe(7)

summary: overview of pipes and FIFOs

text:
# pipe(7)

## NAME
pipe - overview of pipes and FIFOs

## DESCRIPTION
Pipes and FIFOs (also known as named pipes) provide a unidirectional interprocess communication channel. A pipe has a read end and a write end. Data written to the write end of a pipe can be read from the read end of the pipe.

A pipe is created using pipe(2), which creates a new pipe and returns two file descriptors, one referring to the read end of the pipe, the other referring to the write end. Pipes can be used to create a communication channel between related processes; see pipe(2) for an example.

A FIFO (short for First In First Out) has a name within the filesystem (created using mkfifo(3)), and is opened using open(2). Any process may open a FIFO, assuming the file permissions allow it. The read end is opened using the O_RDONLY flag; the write end is opened using the O_WRONLY flag. See fifo(7) for further details. Note: although FIFOs have a pathname in the filesystem, I/O on FIFOs does not involve operations on the underlying device (if there is one).

### I/O on pipes and FIFOs
The only difference between pipes and FIFOs is the manner in which they are created and opened. Once these tasks have been accomplished, I/O on pipes and FIFOs has exactly the same semantics.

If a process attempts to read from an empty pipe, then read(2) will block until data is available. If a process attempts to write to a full pipe (see below), then write(2) blocks until sufficient data has been read from the pipe to allow the write to complete.

Nonblocking I/O is possible by using the fcntl(2) F_SETFL operation to enable the O_NONBLOCK open file status flag or by opening a fifo(7) with O_NONBLOCK. If any process has the pipe open for writing, reads fail with EAGAIN; otherwise—with no potential writers—reads succeed and return empty.

The communication channel provided by a pipe is a byte stream: there is no concept of message boundaries.

If all file descriptors referring to the write end of a pipe have been closed, then an attempt to read(2) from the pipe will see end-of-file (read(2) will return 0). If all file descriptors referring to the read end of a pipe have been closed, then a write(2) will cause a SIGPIPE signal to be generated for the calling process. If the calling process is ignoring this signal, then write(2) fails with the error EPIPE. An application that uses pipe(2) and fork(2) should use suitable close(2) calls to close unnecessary duplicate file descriptors; this ensures that end-of-file and SIGPIPE/EPIPE are delivered when appropriate.

It is not possible to apply lseek(2) to a pipe.

### Pipe capacity
A pipe has a limited capacity. If the pipe is full, then a write(2) will block or fail, depending on whether the O_NONBLOCK flag is set (see below). Different implementations have different limits for the pipe capacity. Applications should not rely on a particular capacity: an application should be designed so that a reading process consumes data as soon as it is available, so that a writing process does not remain blocked.

Before Linux 2.6.11, the capacity of a pipe was the same as the system page size (e.g., 4096 bytes on i386). Since Linux 2.6.11, the pipe capacity is 16 pages (i.e., 65,536 bytes in a system with a page size of 4096 bytes). Since Linux 2.6.35, the default pipe capacity is 16 pages, but the capacity can be queried and set using the fcntl(2) F_GETPIPE_SZ and F_SETPIPE_SZ operations. See fcntl(2) for more information.

The following ioctl(2) operation, which can be applied to a file descriptor that refers to either end of a pipe, places a count of the number of unread bytes in the pipe in the int buffer pointed to by the final argument of the call:

```
ioctl(fd, FIONREAD, &nbytes);
```

The FIONREAD operation is not specified in any standard, but is provided on many implementations.

### /proc files
On Linux, the following files control how much memory can be used for pipes:

/proc/sys/fs/pipe-max-pages (only in Linux 2.6.34)

An upper limit, in pages, on the capacity that an unprivileged user (one without the CAP_SYS_RESOURCE capability) can set for a pipe.

The default value for this limit is 16 times the default pipe capacity (see above); the lower limit is two pages.

This interface was removed in Linux 2.6.35, in favor of /proc/sys/fs/pipe-max-size.

/proc/sys/fs/pipe-max-size (since Linux 2.6.35)

The maximum size (in bytes) of individual pipes that can be set by users without the CAP_SYS_RESOURCE capability. The value assigned to this file may be rounded upward, to reflect the value actually employed for a convenient implementation. To determine the rounded-up value, display the contents of this file after assigning a value to it.

The default value for this file is 1048576 (1 MiB). The minimum value that can be assigned to this file is the system page size. Attempts to set a limit less than the page size cause write(2) to fail with the error EINVAL.

Since Linux 4.9, the value on this file also acts as a ceiling on the default capacity of a new pipe or newly opened FIFO.

/proc/sys/fs/pipe-user-pages-hard (since Linux 4.5)

The hard limit on the total size (in pages) of all pipes created or set by a single unprivileged user (i.e., one with neither the CAP_SYS_RESOURCE nor the CAP_SYS_ADMIN capability). So long as the total number of pages allocated to pipe buffers for this user is at this limit, attempts to create new pipes will be denied, and attempts to increase a pipe's capacity will be denied.

When the value of this limit is zero (which is the default), no hard limit is applied.

/proc/sys/fs/pipe-user-pages-soft (since Linux 4.5)

The soft limit on the total size (in pages) of all pipes created or set by a single unprivileged user (i.e., one with neither the CAP_SYS_RESOURCE nor the CAP_SYS_ADMIN capability). So long as the total number of pages allocated to pipe buffers for this user is at this limit, individual pipes created by a user will be limited to one page, and attempts to increase a pipe's capacity will be denied.

When the value of this limit is zero, no soft limit is applied. The default value for this file is 16384, which permits creating up to 1024 pipes with the default capacity.

Before Linux 4.9, some bugs affected the handling of the pipe-user-pages-soft and pipe-user-pages-hard limits; see BUGS.

### PIPE_BUF
POSIX.1 says that writes of less than PIPE_BUF bytes must be atomic: the output data is written to the pipe as a contiguous sequence. Writes of more than PIPE_BUF bytes may be nonatomic: the kernel may interleave the data with data written by other processes. POSIX.1 requires PIPE_BUF to be at least 512 bytes. (On Linux, PIPE_BUF is 4096 bytes.) The precise semantics depend on whether the file descriptor is nonblocking (O_NONBLOCK), whether there are multiple writers to the pipe, and on n, the number of bytes to be written:

O_NONBLOCK disabled, n <= PIPE_BUF

All n bytes are written atomically; write(2) may block if there is not room for n bytes to be written immediately

O_NONBLOCK enabled, n <= PIPE_BUF

If there is room to write n bytes to the pipe, then write(2) succeeds immediately, writing all n bytes; otherwise write(2) fails, with errno set to EAGAIN.

O_NONBLOCK disabled, n > PIPE_BUF

The write is nonatomic: the data given to write(2) may be interleaved with write(2)s by other process; the write(2) blocks until n bytes have been written.

O_NONBLOCK enabled, n > PIPE_BUF

If the pipe is full, then write(2) fails, with errno set to EAGAIN. Otherwise, from 1 to n bytes may be written (i.e., a "partial write" may occur; the caller should check the return value from write(2) to see how many bytes were actually written), and these bytes may be interleaved with writes by other processes.

### Open file status flags
The only open file status flags that can be meaningfully applied to a pipe or FIFO are O_NONBLOCK and O_ASYNC.

Setting the O_ASYNC flag for the read end of a pipe causes a signal (SIGIO by default) to be generated when new input becomes available on the pipe. The target for delivery of signals must be set using the fcntl(2) F_SETOWN command. On Linux, O_ASYNC is supported for pipes and FIFOs only since Linux 2.6.

### Portability notes
On some systems (but not Linux), pipes are bidirectional: data can be transmitted in both directions between the pipe ends. POSIX.1 requires only unidirectional pipes. Portable applications should avoid reliance on bidirectional pipe semantics.

### BUGS
Before Linux 4.9, some bugs affected the handling of the pipe-user-pages-soft and pipe-user-pages-hard limits when using the fcntl(2) F_SETPIPE_SZ operation to change a pipe's capacity:

(a)

When increasing the pipe capacity, the checks against the soft and hard limits were made against existing consumption, and excluded the memory required for the increased pipe capacity. The new increase in pipe capacity could then push the total memory used by the user for pipes (possibly far) over a limit. (This could also trigger the problem described next.)

Starting with Linux 4.9, the limit checking includes the memory required for the new pipe capacity.

(b)

The limit checks were performed even when the new pipe capacity was less than the existing pipe capacity. This could lead to problems if a user set a large pipe capacity, and then the limits were lowered, with the result that the user could no longer decrease the pipe capacity.

Starting with Linux 4.9, checks against the limits are performed only when increasing a pipe's capacity; an unprivileged user can always decrease a pipe's capacity.

(c)

The accounting and checking against the limits were done as follows:

(1)

Test whether the user has exceeded the limit.

(2)

Make the new pipe buffer allocation.

(3)

Account new allocation against the limits.

This was racey. Multiple processes could pass point (1) simultaneously, and then allocate pipe buffers that were accounted for only in step (3), with the result that the user's pipe buffer allocation could be pushed over the limit.

Starting with Linux 4.9, the accounting step is performed before doing the allocation, and the operation fails if the limit would be exceeded.

Before Linux 4.9, bugs similar to points (a) and (c) could also occur when the kernel allocated memory for a new pipe buffer; that is, when calling pipe(2) and when opening a previously unopened FIFO.

## SEE ALSO
mkfifo(1), dup(2), fcntl(2), open(2), pipe(2), poll(2), select(2), socketpair(2), splice(2), stat(2), tee(2), vmsplice(2), mkfifo(3), epoll(7), fifo(7)


pkeys

title: pkeys(7)

summary: overview of Memory Protection Keys

text:
# pkeys(7)

## NAME
pkeys - overview of Memory Protection Keys

## DESCRIPTION
Memory Protection Keys (pkeys) are an extension to existing page-based memory permissions. Normal page permissions using page tables require expensive system calls and TLB invalidations when changing permissions. Memory Protection Keys provide a mechanism for changing protections without requiring modification of the page tables on every permission change.

To use pkeys, software must first "tag" a page in the page tables with a pkey. After this tag is in place, an application only has to change the contents of a register in order to remove write access, or all access to a tagged page.

Protection keys work in conjunction with the existing PROT_READ, PROT_WRITE, and PROT_EXEC permissions passed to system calls such as mprotect(2) and mmap(2), but always act to further restrict these traditional permission mechanisms.

If a process performs an access that violates pkey restrictions, it receives a SIGSEGV signal. See sigaction(2) for details of the information available with that signal.

To use the pkeys feature, the processor must support it, and the kernel must contain support for the feature on a given processor. As of early 2016 only future Intel x86 processors are supported, and this hardware supports 16 protection keys in each process. However, pkey 0 is used as the default key, so a maximum of 15 are available for actual application use. The default key is assigned to any memory region for which a pkey has not been explicitly assigned via pkey_mprotect(2).

Protection keys have the potential to add a layer of security and reliability to applications. But they have not been primarily designed as a security feature. For instance, WRPKRU is a completely unprivileged instruction, so pkeys are useless in any case that an attacker controls the PKRU register or can execute arbitrary instructions.

Applications should be very careful to ensure that they do not "leak" protection keys. For instance, before calling pkey_free(2), the application should be sure that no memory has that pkey assigned. If the application left the freed pkey assigned, a future user of that pkey might inadvertently change the permissions of an unrelated data structure, which could impact security or stability. The kernel currently allows in-use pkeys to have pkey_free(2) called on them because it would have processor or memory performance implications to perform the additional checks needed to disallow it. Implementation of the necessary checks is left up to applications. Applications may implement these checks by searching the /proc/pid/smaps file for memory regions with the pkey assigned. Further details can be found in proc(5).

Any application wanting to use protection keys needs to be able to function without them. They might be unavailable because the hardware that the application runs on does not support them, the kernel code does not contain support, the kernel support has been disabled, or because the keys have all been allocated, perhaps by a library the application is using. It is recommended that applications wanting to use protection keys should simply call pkey_alloc(2) and test whether the call succeeds, instead of attempting to detect support for the feature in any other way.

Although unnecessary, hardware support for protection keys may be enumerated with the cpuid instruction. Details of how to do this can be found in the Intel Software Developers Manual. The kernel performs this enumeration and exposes the information in /proc/cpuinfo under the "flags" field. The string "pku" in this field indicates hardware support for protection keys and the string "ospke" indicates that the kernel contains and has enabled protection keys support.

Applications using threads and protection keys should be especially careful. Threads inherit the protection key rights of the parent at the time of the clone(2), system call. Applications should either ensure that their own permissions are appropriate for child threads at the time when clone(2) is called, or ensure that each child thread can perform its own initialization of protection key rights.

### Signal Handler Behavior
Each time a signal handler is invoked (including nested signals), the thread is temporarily given a new, default set of protection key rights that override the rights from the interrupted context. This means that applications must re-establish their desired protection key rights upon entering a signal handler if the desired rights differ from the defaults. The rights of any interrupted context are restored when the signal handler returns.

This signal behavior is unusual and is due to the fact that the x86 PKRU register (which stores protection key access rights) is managed with the same hardware mechanism (XSAVE) that manages floating-point registers. The signal behavior is the same as that of floating-point registers.

### Protection Keys system calls
The Linux kernel implements the following pkey-related system calls: pkey_mprotect(2), pkey_alloc(2), and pkey_free(2).

The Linux pkey system calls are available only if the kernel was configured and built with the CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS option.

## EXAMPLES
The program below allocates a page of memory with read and write permissions. It then writes some data to the memory and successfully reads it back. After that, it attempts to allocate a protection key and disallows access to the page by using the WRPKRU instruction. It then tries to access the page, which we now expect to cause a fatal signal to the application.

```
$ ./a.out
buffer contains: 73
about to read buffer again...
Segmentation fault (core dumped)
```

### Program source

```
#define _GNU_SOURCE
#include <err.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
int
main(void)
{

    int status;

    int pkey;

    int *buffer;

    /*

     * Allocate one page of memory.

     */

    buffer = mmap(NULL, getpagesize(), PROT_READ | PROT_WRITE,

                  MAP_ANONYMOUS | MAP_PRIVATE, -1, 0);

    if (buffer == MAP_FAILED)

        err(EXIT_FAILURE, "mmap");

    /*

     * Put some random data into the page (still OK to touch).

     */

    *buffer = __LINE__;

    printf("buffer contains: %d\n", *buffer);

    /*

     * Allocate a protection key:

     */

    pkey = pkey_alloc(0, 0);

    if (pkey == -1)

        err(EXIT_FAILURE, "pkey_alloc");

    /*

     * Disable access to any memory with "pkey" set,

     * even though there is none right now.

     */

    status = pkey_set(pkey, PKEY_DISABLE_ACCESS);

    if (status)

        err(EXIT_FAILURE, "pkey_set");

    /*

     * Set the protection key on "buffer".

     * Note that it is still read/write as far as mprotect() is

     * concerned and the previous pkey_set() overrides it.

     */

    status = pkey_mprotect(buffer, getpagesize(),

                           PROT_READ | PROT_WRITE, pkey);

    if (status == -1)

        err(EXIT_FAILURE, "pkey_mprotect");

    printf("about to read buffer again...\n");

    /*

     * This will crash, because we have disallowed access.

     */

    printf("buffer contains: %d\n", *buffer);

    status = pkey_free(pkey);

    if (status == -1)

        err(EXIT_FAILURE, "pkey_free");

    exit(EXIT_SUCCESS);
}
```

## SEE ALSO
pkey_alloc(2), pkey_free(2), pkey_mprotect(2), sigaction(2)


posixoptions

title: posixoptions(7)

summary: optional parts of the POSIX standard

text:
# posixoptions(7)

## NAME
posixoptions - optional parts of the POSIX standard

## DESCRIPTION
The POSIX standard (the information below is from POSIX.1-2001) describes a set of behaviors and interfaces for a compliant system. However, many interfaces are optional and there are feature test macros to test the availability of interfaces at compile time, and functions sysconf(3), fpathconf(3), pathconf(3), confstr(3) to do this at run time. From shell scripts one can use getconf(1). For more detail, see sysconf(3).

We give the name of the POSIX abbreviation, the option, the name of the sysconf(3) parameter used to inquire about the option, and possibly a very short description. Much more precise detail can be found in the POSIX standard itself, versions of which can nowadays be accessed freely on the web.

### ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO
The following advisory functions are present:

```
posix_fadvise()
posix_fallocate()
posix_memalign()
posix_madvise()
```

### AIO - _POSIX_ASYNCHRONOUS_IO - _SC_ASYNCHRONOUS_IO
The header <aio.h> is present. The following functions are present:

```
aio_cancel()
aio_error()
aio_fsync()
aio_read()
aio_return()
aio_suspend()
aio_write()
lio_listio()
```

### BAR - _POSIX_BARRIERS - _SC_BARRIERS
This option implies the _POSIX_THREADS and _POSIX_THREAD_SAFE_FUNCTIONS options. The following functions are present:

```
pthread_barrier_destroy()
pthread_barrier_init()
pthread_barrier_wait()
pthread_barrierattr_destroy()
pthread_barrierattr_init()
```

### --- - POSIX_CHOWN_RESTRICTED
If this option is in effect (as it always is under POSIX.1-2001), then only root may change the owner of a file, and nonroot can set the group of a file only to one of the groups it belongs to. This affects the following functions

```
chown()
fchown()
```

### CS - _POSIX_CLOCK_SELECTION - _SC_CLOCK_SELECTION
This option implies the _POSIX_TIMERS option. The following functions are present:

```
pthread_condattr_getclock()
pthread_condattr_setclock()
clock_nanosleep()
```

If CLOCK_REALTIME is changed by the function clock_settime(), then this affects all timers set for an absolute time.

### CPT - _POSIX_CPUTIME - _SC_CPUTIME
The CLOCK_PROCESS_CPUTIME_ID clock ID is supported. The initial value of this clock is 0 for each process. This option implies the _POSIX_TIMERS option. The function clock_getcpuclockid() is present.

### --- - _POSIX_FILE_LOCKING - _SC_FILE_LOCKING
This option has been deleted. Not in final XPG6.

### FSC - _POSIX_FSYNC - _SC_FSYNC
The function fsync() is present.

### IP6 - _POSIX_IPV6 - _SC_IPV6
Internet Protocol Version 6 is supported.

### --- - _POSIX_JOB_CONTROL - _SC_JOB_CONTROL
If this option is in effect (as it always is under POSIX.1-2001), then the system implements POSIX-style job control, and the following functions are present:

```
setpgid()
tcdrain()
tcflush()
tcgetpgrp()
tcsendbreak()
tcsetattr()
tcsetpgrp()
```

### MF - _POSIX_MAPPED_FILES - _SC_MAPPED_FILES
Shared memory is supported. The include file <sys/mman.h> is present. The following functions are present:

```
mmap()
msync()
munmap()
```

### ML - _POSIX_MEMLOCK - _SC_MEMLOCK
Shared memory can be locked into core. The following functions are present:

```
mlockall()
munlockall()
```

### MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE
More precisely, ranges can be locked into core. The following functions are present:

```
mlock()
munlock()
```

### MPR - _POSIX_MEMORY_PROTECTION - _SC_MEMORY_PROTECTION
The function mprotect() is present.

### MSG - _POSIX_MESSAGE_PASSING - _SC_MESSAGE_PASSING
The include file <mqueue.h> is present. The following functions are present:

```
mq_close()
mq_getattr()
mq_notify()
mq_open()
mq_receive()
mq_send()
mq_setattr()
mq_unlink()
```

### MON - _POSIX_MONOTONIC_CLOCK - _SC_MONOTONIC_CLOCK
CLOCK_MONOTONIC is supported. This option implies the _POSIX_TIMERS option. The following functions are affected:

```
aio_suspend()
clock_getres()
clock_gettime()
clock_settime()
timer_create()
```

### --- - _POSIX_MULTI_PROCESS - _SC_MULTI_PROCESS
This option has been deleted. Not in final XPG6.

### --- - _POSIX_NO_TRUNC
If this option is in effect (as it always is under POSIX.1-2001), then pathname components longer than NAME_MAX are not truncated, but give an error. This property may be dependent on the path prefix of the component.

### PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO
This option says that one can specify priorities for asynchronous I/O. This affects the functions

```
aio_read()
aio_write()
```

### PS - _POSIX_PRIORITY_SCHEDULING - _SC_PRIORITY_SCHEDULING
The include file <sched.h> is present. The following functions are present:

```
sched_get_priority_max()
sched_get_priority_min()
sched_getparam()
sched_getscheduler()
sched_rr_get_interval()
sched_setparam()
sched_setscheduler()
sched_yield()
```

If also _POSIX_SPAWN is in effect, then the following functions are present:

```
posix_spawnattr_getschedparam()
posix_spawnattr_getschedpolicy()
posix_spawnattr_setschedparam()
posix_spawnattr_setschedpolicy()
```

### RS - _POSIX_RAW_SOCKETS
Raw sockets are supported. The following functions are affected:

```
getsockopt()
setsockopt()
```

### --- - _POSIX_READER_WRITER_LOCKS - _SC_READER_WRITER_LOCKS
This option implies the _POSIX_THREADS option. Conversely, under POSIX.1-2001 the _POSIX_THREADS option implies this option.

The following functions are present:

```
pthread_rwlock_destroy()
pthread_rwlock_init()
pthread_rwlock_rdlock()
pthread_rwlock_tryrdlock()
pthread_rwlock_trywrlock()
pthread_rwlock_unlock()
pthread_rwlock_wrlock()
pthread_rwlockattr_destroy()
pthread_rwlockattr_init()
```

### RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS
Realtime signals are supported. The following functions are present:

```
sigqueue()
sigtimedwait()
sigwaitinfo()
```

### --- - _POSIX_REGEXP - _SC_REGEXP
If this option is in effect (as it always is under POSIX.1-2001), then POSIX regular expressions are supported and the following functions are present:

```
regcomp()
regerror()
regexec()
regfree()
```

### --- - _POSIX_SAVED_IDS - _SC_SAVED_IDS
If this option is in effect (as it always is under POSIX.1-2001), then a process has a saved set-user-ID and a saved set-group-ID. The following functions are affected:

```
exec()
kill()
seteuid()
setegid()
setgid()
setuid()
```

### SEM - _POSIX_SEMAPHORES - _SC_SEMAPHORES
The include file <semaphore.h> is present. The following functions are present:

```
sem_close()
sem_destroy()
sem_getvalue()
sem_init()
sem_open()
sem_post()
sem_trywait()
sem_unlink()
sem_wait()
```

### SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS
The following functions are present:

```
mmap()
munmap()
shm_open()
shm_unlink()
```

### --- - _POSIX_SHELL - _SC_SHELL
If this option is in effect (as it always is under POSIX.1-2001), the function system() is present.

### SPN - _POSIX_SPAWN - _SC_SPAWN
This option describes support for process creation in a context where it is difficult or impossible to use fork(), for example, because no MMU is present.

If _POSIX_SPAWN is in effect, then the include file <spawn.h> and the following functions are present:

```
posix_spawn()
posix_spawn_file_actions_addclose()
posix_spawn_file_actions_adddup2()
posix_spawn_file_actions_addopen()
posix_spawn_file_actions_destroy()
posix_spawn_file_actions_init()
posix_spawnattr_destroy()
posix_spawnattr_getsigdefault()
posix_spawnattr_getflags()
posix_spawnattr_getpgroup()
posix_spawnattr_getsigmask()
posix_spawnattr_init()
posix_spawnattr_setsigdefault()
posix_spawnattr_setflags()
posix_spawnattr_setpgroup()
posix_spawnattr_setsigmask()
posix_spawnp()
```

If also _POSIX_PRIORITY_SCHEDULING is in effect, then the following functions are present:

```
posix_spawnattr_getschedparam()
posix_spawnattr_getschedpolicy()
posix_spawnattr_setschedparam()
posix_spawnattr_setschedpolicy()
```

### SPI - _POSIX_SPIN_LOCKS - _SC_SPIN_LOCKS
This option implies the _POSIX_THREADS and _POSIX_THREAD_SAFE_FUNCTIONS options. The following functions are present:

```
pthread_spin_destroy()
pthread_spin_init()
pthread_spin_lock()
pthread_spin_trylock()
pthread_spin_unlock()
```

### SS - _POSIX_SPORADIC_SERVER - _SC_SPORADIC_SERVER
The scheduling policy SCHED_SPORADIC is supported. This option implies the _POSIX_PRIORITY_SCHEDULING option. The following functions are affected:

```
sched_setparam()
sched_setscheduler()
```

### SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO
The following functions are affected:

```
open()
msync()
fsync()
fdatasync()
```

### TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR
The following functions are affected:

```
pthread_attr_getstack()
pthread_attr_getstackaddr()
pthread_attr_setstack()
pthread_attr_setstackaddr()
```

### TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE
The following functions are affected:

```
pthread_attr_getstack()
pthread_attr_getstacksize()
pthread_attr_setstack()
pthread_attr_setstacksize()
```

### TCT - _POSIX_THREAD_CPUTIME - _SC_THREAD_CPUTIME
The clockID CLOCK_THREAD_CPUTIME_ID is supported. This option implies the _POSIX_TIMERS option. The following functions are affected:

```
pthread_getcpuclockid()
clock_getres()
clock_gettime()
clock_settime()
timer_create()
```

### TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT
The following functions are affected:

```
pthread_mutexattr_getprotocol()
pthread_mutexattr_setprotocol()
```

### TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT
The following functions are affected:

```
pthread_mutex_getprioceiling()
pthread_mutex_setprioceiling()
pthread_mutexattr_getprioceiling()
pthread_mutexattr_getprotocol()
pthread_mutexattr_setprioceiling()
pthread_mutexattr_setprotocol()
```

### TPS - _POSIX_THREAD_PRIORITY_SCHEDULING - _SC_THREAD_PRIORITY_SCHEDULING
If this option is in effect, the different threads inside a process can run with different priorities and/or different schedulers. The following functions are affected:

```
pthread_attr_getinheritsched()
pthread_attr_getschedpolicy()
pthread_attr_getscope()
pthread_attr_setinheritsched()
pthread_attr_setschedpolicy()
pthread_attr_setscope()
pthread_getschedparam()
pthread_setschedparam()
pthread_setschedprio()
```

### TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED
The following functions are affected:

```
pthread_barrierattr_getpshared()
pthread_barrierattr_setpshared()
pthread_condattr_getpshared()
pthread_condattr_setpshared()
pthread_mutexattr_getpshared()
pthread_mutexattr_setpshared()
pthread_rwlockattr_getpshared()
pthread_rwlockattr_setpshared()
```

### TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS
The following functions are affected:

```
readdir_r()
getgrgid_r()
getgrnam_r()
getpwnam_r()
getpwuid_r()
flockfile()
ftrylockfile()
funlockfile()
getc_unlocked()
getchar_unlocked()
putc_unlocked()
putchar_unlocked()
rand_r()
strerror_r()
strtok_r()
asctime_r()
ctime_r()
gmtime_r()
localtime_r()
```

### TSP - _POSIX_THREAD_SPORADIC_SERVER - _SC_THREAD_SPORADIC_SERVER
This option implies the _POSIX_THREAD_PRIORITY_SCHEDULING option. The following functions are affected:

```
sched_getparam()
sched_setparam()
sched_setscheduler()
```

### THR - _POSIX_THREADS - _SC_THREADS
Basic support for POSIX threads is available. The following functions are present:

```
pthread_atfork()
pthread_attr_destroy()
pthread_attr_getdetachstate()
pthread_attr_getschedparam()
pthread_attr_init()
pthread_attr_setdetachstate()
pthread_attr_setschedparam()
pthread_cancel()
pthread_cleanup_push()
pthread_cleanup_pop()
pthread_cond_broadcast()
pthread_cond_destroy()
pthread_cond_init()
pthread_cond_signal()
pthread_cond_timedwait()
pthread_cond_wait()
pthread_condattr_destroy()
pthread_condattr_init()
pthread_create()
pthread_detach()
pthread_equal()
pthread_exit()
pthread_getspecific()
pthread_join()
pthread_key_create()
pthread_key_delete()
pthread_mutex_destroy()
pthread_mutex_init()
pthread_mutex_lock()
pthread_mutex_trylock()
pthread_mutex_unlock()
pthread_mutexattr_destroy()
pthread_mutexattr_init()
pthread_once()
pthread_rwlock_destroy()
pthread_rwlock_init()
pthread_rwlock_rdlock()
pthread_rwlock_tryrdlock()
pthread_rwlock_trywrlock()
pthread_rwlock_unlock()
pthread_rwlock_wrlock()
pthread_rwlockattr_destroy()
pthread_rwlockattr_init()
pthread_self()
pthread_setcancelstate()
pthread_setcanceltype()
pthread_setspecific()
pthread_testcancel()
```

### TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS
The following functions are present:

```
mq_timedreceive()
mq_timedsend()
pthread_mutex_timedlock()
pthread_rwlock_timedrdlock()
pthread_rwlock_timedwrlock()
sem_timedwait()
posix_trace_timedgetnext_event()
```

### TMR - _POSIX_TIMERS - _SC_TIMERS
The following functions are present:

```
clock_getres()
clock_gettime()
clock_settime()
nanosleep()
timer_create()
timer_delete()
timer_gettime()
timer_getoverrun()
timer_settime()
```

### TRC - _POSIX_TRACE - _SC_TRACE
POSIX tracing is available. The following functions are present:

```
posix_trace_attr_destroy()
posix_trace_attr_getclockres()
posix_trace_attr_getcreatetime()
posix_trace_attr_getgenversion()
posix_trace_attr_getmaxdatasize()
posix_trace_attr_getmaxsystemeventsize()
posix_trace_attr_getmaxusereventsize()
posix_trace_attr_getname()
posix_trace_attr_getstreamfullpolicy()
posix_trace_attr_getstreamsize()
posix_trace_attr_init()
posix_trace_attr_setmaxdatasize()
posix_trace_attr_setname()
posix_trace_attr_setstreamsize()
posix_trace_attr_setstreamfullpolicy()
posix_trace_clear()
posix_trace_create()
posix_trace_event()
posix_trace_eventid_equal()
posix_trace_eventid_get_name()
posix_trace_eventid_open()
posix_trace_eventtypelist_getnext_id()
posix_trace_eventtypelist_rewind()
posix_trace_flush()
posix_trace_get_attr()
posix_trace_get_status()
posix_trace_getnext_event()
posix_trace_shutdown()
posix_trace_start()
posix_trace_stop()
posix_trace_trygetnext_event()
```

### TEF - _POSIX_TRACE_EVENT_FILTER - _SC_TRACE_EVENT_FILTER
This option implies the _POSIX_TRACE option. The following functions are present:

```
posix_trace_eventset_add()
posix_trace_eventset_del()
posix_trace_eventset_empty()
posix_trace_eventset_fill()
posix_trace_eventset_ismember()
posix_trace_get_filter()
posix_trace_set_filter()
posix_trace_trid_eventid_open()
```

### TRI - _POSIX_TRACE_INHERIT - _SC_TRACE_INHERIT
Tracing children of the traced process is supported. This option implies the _POSIX_TRACE option. The following functions are present:

```
posix_trace_attr_getinherited()
posix_trace_attr_setinherited()
```

### TRL - _POSIX_TRACE_LOG - _SC_TRACE_LOG
This option implies the _POSIX_TRACE option. The following functions are present:

```
posix_trace_attr_getlogfullpolicy()
posix_trace_attr_getlogsize()
posix_trace_attr_setlogfullpolicy()
posix_trace_attr_setlogsize()
posix_trace_close()
posix_trace_create_withlog()
posix_trace_open()
posix_trace_rewind()
```

### TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT
The following functions are present:

```
posix_mem_offset()
posix_typed_mem_get_info()
posix_typed_mem_open()
```

### --- - _POSIX_VDISABLE
Always present (probably 0). Value to set a changeable special control character to indicate that it is disabled.

## X/OPEN SYSTEM INTERFACE EXTENSIONS

### XSI - _XOPEN_CRYPT - _SC_XOPEN_CRYPT
The following functions are present:

```
crypt()
encrypt()
setkey()
```

### XSI - _XOPEN_REALTIME - _SC_XOPEN_REALTIME
This option implies the following options:

_POSIX_ASYNCHRONOUS_IO==200112L

_POSIX_FSYNC

_POSIX_MAPPED_FILES

_POSIX_MEMLOCK==200112L

_POSIX_MEMLOCK_RANGE==200112L

_POSIX_MEMORY_PROTECTION

_POSIX_MESSAGE_PASSING==200112L

_POSIX_PRIORITIZED_IO

_POSIX_PRIORITY_SCHEDULING==200112L

_POSIX_REALTIME_SIGNALS==200112L

_POSIX_SEMAPHORES==200112L

_POSIX_SHARED_MEMORY_OBJECTS==200112L

_POSIX_SYNCHRONIZED_IO==200112L

_POSIX_TIMERS==200112L

### ADV - --- - ---
The Advanced Realtime option group implies that the following options are all defined to 200112L:

_POSIX_ADVISORY_INFO

_POSIX_CLOCK_SELECTION

(implies _POSIX_TIMERS)

_POSIX_CPUTIME

(implies _POSIX_TIMERS)

_POSIX_MONOTONIC_CLOCK

(implies _POSIX_TIMERS)

_POSIX_SPAWN

_POSIX_SPORADIC_SERVER

(implies _POSIX_PRIORITY_SCHEDULING)

_POSIX_TIMEOUTS

_POSIX_TYPED_MEMORY_OBJECTS

### XSI - _XOPEN_REALTIME_THREADS - _SC_XOPEN_REALTIME_THREADS
This option implies that the following options are all defined to 200112L:

_POSIX_THREAD_PRIO_INHERIT

_POSIX_THREAD_PRIO_PROTECT

_POSIX_THREAD_PRIORITY_SCHEDULING

### ADVANCED REALTIME THREADS - --- - ---
This option implies that the following options are all defined to 200112L:

_POSIX_BARRIERS

(implies _POSIX_THREADS, _POSIX_THREAD_SAFE_FUNCTIONS)

_POSIX_SPIN_LOCKS

(implies _POSIX_THREADS, _POSIX_THREAD_SAFE_FUNCTIONS)

_POSIX_THREAD_CPUTIME

(implies _POSIX_TIMERS)

_POSIX_THREAD_SPORADIC_SERVER

(implies _POSIX_THREAD_PRIORITY_SCHEDULING)

### TRACING - --- - ---
This option implies that the following options are all defined to 200112L:

_POSIX_TRACE

_POSIX_TRACE_EVENT_FILTER

_POSIX_TRACE_LOG

_POSIX_TRACE_INHERIT

### STREAMS - _XOPEN_STREAMS - _SC_XOPEN_STREAMS
The following functions are present:

```
fattach()
fdetach()
getmsg()
getpmsg()
ioctl()
isastream()
putmsg()
putpmsg()
```

### XSI - _XOPEN_LEGACY - _SC_XOPEN_LEGACY
Functions included in the legacy option group were previously mandatory, but are now optional in this version. The following functions are present:

```
bcmp()
bcopy()
bzero()
ecvt()
fcvt()
ftime()
gcvt()
getwd()
index()
mktemp()
rindex()
utimes()
wcswcs()
```

### XSI - _XOPEN_UNIX - _SC_XOPEN_UNIX
The following functions are present:

```
mmap()
munmap()
msync()
```

This option implies the following options:

_POSIX_FSYNC

_POSIX_MAPPED_FILES

_POSIX_MEMORY_PROTECTION

_POSIX_THREAD_ATTR_STACKADDR

_POSIX_THREAD_ATTR_STACKSIZE

_POSIX_THREAD_PROCESS_SHARED

_POSIX_THREAD_SAFE_FUNCTIONS

_POSIX_THREADS

This option may imply the following options from the XSI option groups:

Encryption (_XOPEN_CRYPT)

Realtime (_XOPEN_REALTIME)

Advanced Realtime (ADB)

Realtime Threads (_XOPEN_REALTIME_THREADS)

Advanced Realtime Threads (ADVANCED REALTIME THREADS)

Tracing (TRACING)

XSI Streams (STREAMS)

Legacy (_XOPEN_LEGACY)

## SEE ALSO
sysconf(3), standards(7)


process-keyring

title: process-keyring(7)

summary: per-process shared keyring

text:
# process-keyring(7)

## NAME
process-keyring - per-process shared keyring

## DESCRIPTION
The process keyring is a keyring used to anchor keys on behalf of a process. It is created only when a process requests it. The process keyring has the name (description) _pid.

A special serial number value, KEY_SPEC_PROCESS_KEYRING, is defined that can be used in lieu of the actual serial number of the calling process's process keyring.

From the keyctl(1) utility, '@p' can be used instead of a numeric key ID in much the same way, but since keyctl(1) is a program run after forking, this is of no utility.

A thread created using the clone(2) CLONE_THREAD flag has the same process keyring as the caller of clone(2). When a new process is created using fork() it initially has no process keyring. A process's process keyring is cleared on execve(2). The process keyring is destroyed when the last thread that refers to it terminates.

If a process doesn't have a process keyring when it is accessed, then the process keyring will be created if the keyring is to be modified; otherwise, the error ENOKEY results.

## SEE ALSO
keyctl(1), keyctl(3), keyrings(7), persistent-keyring(7), session-keyring(7), thread-keyring(7), user-keyring(7), user-session-keyring(7)


pthreads

title: pthreads(7)

summary: POSIX threads

text:
# pthreads(7)

## NAME
pthreads - POSIX threads

## DESCRIPTION
POSIX.1 specifies a set of interfaces (functions, header files) for threaded programming commonly known as POSIX threads, or Pthreads. A single process can contain multiple threads, all of which are executing the same program. These threads share the same global memory (data and heap segments), but each thread has its own stack (automatic variables).

POSIX.1 also requires that threads share a range of other attributes (i.e., these attributes are process-wide rather than per-thread):

•

process ID

•

parent process ID

•

process group ID and session ID

•

controlling terminal

•

user and group IDs

•

open file descriptors

•

record locks (see fcntl(2))

•

signal dispositions

•

file mode creation mask (umask(2))

•

current directory (chdir(2)) and root directory (chroot(2))

•

interval timers (setitimer(2)) and POSIX timers (timer_create(2))

•

nice value (setpriority(2))

•

resource limits (setrlimit(2))

•

measurements of the consumption of CPU time (times(2)) and resources (getrusage(2))

As well as the stack, POSIX.1 specifies that various other attributes are distinct for each thread, including:

•

thread ID (the pthread_t data type)

•

signal mask (pthread_sigmask(3))

•

the errno variable

•

alternate signal stack (sigaltstack(2))

•

real-time scheduling policy and priority (sched(7))

The following Linux-specific features are also per-thread:

•

capabilities (see capabilities(7))

•

CPU affinity (sched_setaffinity(2))

### Pthreads function return values
Most pthreads functions return 0 on success, and an error number on failure. The error numbers that can be returned have the same meaning as the error numbers returned in errno by conventional system calls and C library functions. Note that the pthreads functions do not set errno. For each of the pthreads functions that can return an error, POSIX.1-2001 specifies that the function can never fail with the error EINTR.

### Thread IDs
Each of the threads in a process has a unique thread identifier (stored in the type pthread_t). This identifier is returned to the caller of pthread_create(3), and a thread can obtain its own thread identifier using pthread_self(3).

Thread IDs are guaranteed to be unique only within a process. (In all pthreads functions that accept a thread ID as an argument, that ID by definition refers to a thread in the same process as the caller.)

The system may reuse a thread ID after a terminated thread has been joined, or a detached thread has terminated. POSIX says: "If an application attempts to use a thread ID whose lifetime has ended, the behavior is undefined."

### Thread-safe functions
A thread-safe function is one that can be safely (i.e., it will deliver the same results regardless of whether it is) called from multiple threads at the same time.

POSIX.1-2001 and POSIX.1-2008 require that all functions specified in the standard shall be thread-safe, except for the following functions:

```
asctime()
basename()
catgets()
crypt()
ctermid() if passed a non-NULL argument
ctime()
dbm_clearerr()
dbm_close()
dbm_delete()
dbm_error()
dbm_fetch()
dbm_firstkey()
dbm_nextkey()
dbm_open()
dbm_store()
dirname()
dlerror()
drand48()
ecvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
encrypt()
endgrent()
endpwent()
endutxent()
fcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
ftw()
gcvt() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
getc_unlocked()
getchar_unlocked()
getdate()
getenv()
getgrent()
getgrgid()
getgrnam()
gethostbyaddr() [POSIX.1-2001 only (function removed in

                 POSIX.1-2008)]
gethostbyname() [POSIX.1-2001 only (function removed in

                 POSIX.1-2008)]
gethostent()
getlogin()
getnetbyaddr()
getnetbyname()
getnetent()
getopt()
getprotobyname()
getprotobynumber()
getprotoent()
getpwent()
getpwnam()
getpwuid()
getservbyname()
getservbyport()
getservent()
getutxent()
getutxid()
getutxline()
gmtime()
hcreate()
hdestroy()
hsearch()
inet_ntoa()
l64a()
lgamma()
lgammaf()
lgammal()
localeconv()
localtime()
lrand48()
mrand48()
nftw()
nl_langinfo()
ptsname()
putc_unlocked()
putchar_unlocked()
putenv()
pututxline()
rand()
readdir()
setenv()
setgrent()
setkey()
setpwent()
setutxent()
strerror()
strsignal() [Added in POSIX.1-2008]
strtok()
system() [Added in POSIX.1-2008]
tmpnam() if passed a non-NULL argument
ttyname()
unsetenv()
wcrtomb() if its final argument is NULL
wcsrtombs() if its final argument is NULL
wcstombs()
wctomb()
```

### Async-cancel-safe functions
An async-cancel-safe function is one that can be safely called in an application where asynchronous cancelability is enabled (see pthread_setcancelstate(3)).

Only the following functions are required to be async-cancel-safe by POSIX.1-2001 and POSIX.1-2008:

```
pthread_cancel()
pthread_setcancelstate()
pthread_setcanceltype()
```

### Cancelation points
POSIX.1 specifies that certain functions must, and certain other functions may, be cancelation points. If a thread is cancelable, its cancelability type is deferred, and a cancelation request is pending for the thread, then the thread is canceled when it calls a function that is a cancelation point.

The following functions are required to be cancelation points by POSIX.1-2001 and/or POSIX.1-2008:

```
accept()
aio_suspend()
clock_nanosleep()
close()
connect()
creat()
fcntl() F_SETLKW
fdatasync()
fsync()
getmsg()
getpmsg()
lockf() F_LOCK
mq_receive()
mq_send()
mq_timedreceive()
mq_timedsend()
msgrcv()
msgsnd()
msync()
nanosleep()
open()
openat() [Added in POSIX.1-2008]
pause()
poll()
pread()
pselect()
pthread_cond_timedwait()
pthread_cond_wait()
pthread_join()
pthread_testcancel()
putmsg()
putpmsg()
pwrite()
read()
readv()
recv()
recvfrom()
recvmsg()
select()
sem_timedwait()
sem_wait()
send()
sendmsg()
sendto()
sigpause() [POSIX.1-2001 only (moves to "may" list in POSIX.1-2008)]
sigsuspend()
sigtimedwait()
sigwait()
sigwaitinfo()
sleep()
system()
tcdrain()
usleep() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
wait()
waitid()
waitpid()
write()
writev()
```

The following functions may be cancelation points according to POSIX.1-2001 and/or POSIX.1-2008:

```
access()
asctime()
asctime_r()
catclose()
catgets()
catopen()
chmod() [Added in POSIX.1-2008]
chown() [Added in POSIX.1-2008]
closedir()
closelog()
ctermid()
ctime()
ctime_r()
dbm_close()
dbm_delete()
dbm_fetch()
dbm_nextkey()
dbm_open()
dbm_store()
dlclose()
dlopen()
dprintf() [Added in POSIX.1-2008]
endgrent()
endhostent()
endnetent()
endprotoent()
endpwent()
endservent()
endutxent()
faccessat() [Added in POSIX.1-2008]
fchmod() [Added in POSIX.1-2008]
fchmodat() [Added in POSIX.1-2008]
fchown() [Added in POSIX.1-2008]
fchownat() [Added in POSIX.1-2008]
fclose()
fcntl() (for any value of cmd argument)
fflush()
fgetc()
fgetpos()
fgets()
fgetwc()
fgetws()
fmtmsg()
fopen()
fpathconf()
fprintf()
fputc()
fputs()
fputwc()
fputws()
fread()
freopen()
fscanf()
fseek()
fseeko()
fsetpos()
fstat()
fstatat() [Added in POSIX.1-2008]
ftell()
ftello()
ftw()
futimens() [Added in POSIX.1-2008]
fwprintf()
fwrite()
fwscanf()
getaddrinfo()
getc()
getc_unlocked()
getchar()
getchar_unlocked()
getcwd()
getdate()
getdelim() [Added in POSIX.1-2008]
getgrent()
getgrgid()
getgrgid_r()
getgrnam()
getgrnam_r()
gethostbyaddr() [POSIX.1-2001 only (function removed in

                 POSIX.1-2008)]
gethostbyname() [POSIX.1-2001 only (function removed in

                 POSIX.1-2008)]
gethostent()
gethostid()
gethostname()
getline() [Added in POSIX.1-2008]
getlogin()
getlogin_r()
getnameinfo()
getnetbyaddr()
getnetbyname()
getnetent()
getopt() (if opterr is nonzero)
getprotobyname()
getprotobynumber()
getprotoent()
getpwent()
getpwnam()
getpwnam_r()
getpwuid()
getpwuid_r()
gets()
getservbyname()
getservbyport()
getservent()
getutxent()
getutxid()
getutxline()
getwc()
getwchar()
getwd() [POSIX.1-2001 only (function removed in POSIX.1-2008)]
glob()
iconv_close()
iconv_open()
ioctl()
link()
linkat() [Added in POSIX.1-2008]
lio_listio() [Added in POSIX.1-2008]
localtime()
localtime_r()
lockf() [Added in POSIX.1-2008]
lseek()
lstat()
mkdir() [Added in POSIX.1-2008]
mkdirat() [Added in POSIX.1-2008]
mkdtemp() [Added in POSIX.1-2008]
mkfifo() [Added in POSIX.1-2008]
mkfifoat() [Added in POSIX.1-2008]
mknod() [Added in POSIX.1-2008]
mknodat() [Added in POSIX.1-2008]
mkstemp()
mktime()
nftw()
opendir()
openlog()
pathconf()
pclose()
perror()
popen()
posix_fadvise()
posix_fallocate()
posix_madvise()
posix_openpt()
posix_spawn()
posix_spawnp()
posix_trace_clear()
posix_trace_close()
posix_trace_create()
posix_trace_create_withlog()
posix_trace_eventtypelist_getnext_id()
posix_trace_eventtypelist_rewind()
posix_trace_flush()
posix_trace_get_attr()
posix_trace_get_filter()
posix_trace_get_status()
posix_trace_getnext_event()
posix_trace_open()
posix_trace_rewind()
posix_trace_set_filter()
posix_trace_shutdown()
posix_trace_timedgetnext_event()
posix_typed_mem_open()
printf()
psiginfo() [Added in POSIX.1-2008]
psignal() [Added in POSIX.1-2008]
pthread_rwlock_rdlock()
pthread_rwlock_timedrdlock()
pthread_rwlock_timedwrlock()
pthread_rwlock_wrlock()
putc()
putc_unlocked()
putchar()
putchar_unlocked()
puts()
pututxline()
putwc()
putwchar()
readdir()
readdir_r()
readlink() [Added in POSIX.1-2008]
readlinkat() [Added in POSIX.1-2008]
remove()
rename()
renameat() [Added in POSIX.1-2008]
rewind()
rewinddir()
scandir() [Added in POSIX.1-2008]
scanf()
seekdir()
semop()
setgrent()
sethostent()
setnetent()
setprotoent()
setpwent()
setservent()
setutxent()
sigpause() [Added in POSIX.1-2008]
stat()
strerror()
strerror_r()
strftime()
symlink()
symlinkat() [Added in POSIX.1-2008]
sync()
syslog()
tmpfile()
tmpnam()
ttyname()
ttyname_r()
tzset()
ungetc()
ungetwc()
unlink()
unlinkat() [Added in POSIX.1-2008]
utime() [Added in POSIX.1-2008]
utimensat() [Added in POSIX.1-2008]
utimes() [Added in POSIX.1-2008]
vdprintf() [Added in POSIX.1-2008]
vfprintf()
vfwprintf()
vprintf()
vwprintf()
wcsftime()
wordexp()
wprintf()
wscanf()
```

An implementation may also mark other functions not specified in the standard as cancelation points. In particular, an implementation is likely to mark any nonstandard function that may block as a cancelation point. (This includes most functions that can touch files.)

It should be noted that even if an application is not using asynchronous cancelation, that calling a function from the above list from an asynchronous signal handler may cause the equivalent of asynchronous cancelation. The underlying user code may not expect asynchronous cancelation and the state of the user data may become inconsistent. Therefore signals should be used with caution when entering a region of deferred cancelation.

### Compiling on Linux
On Linux, programs that use the Pthreads API should be compiled using cc -pthread.

### Linux implementations of POSIX threads
Over time, two threading implementations have been provided by the GNU C library on Linux:

LinuxThreads

This is the original Pthreads implementation. Since glibc 2.4, this implementation is no longer supported.

NPTL (Native POSIX Threads Library)

This is the modern Pthreads implementation. By comparison with LinuxThreads, NPTL provides closer conformance to the requirements of the POSIX.1 specification and better performance when creating large numbers of threads. NPTL is available since glibc 2.3.2, and requires features that are present in the Linux 2.6 kernel.

Both of these are so-called 1:1 implementations, meaning that each thread maps to a kernel scheduling entity. Both threading implementations employ the Linux clone(2) system call. In NPTL, thread synchronization primitives (mutexes, thread joining, and so on) are implemented using the Linux futex(2) system call.

### LinuxThreads
The notable features of this implementation are the following:

•

In addition to the main (initial) thread, and the threads that the program creates using pthread_create(3), the implementation creates a "manager" thread. This thread handles thread creation and termination. (Problems can result if this thread is inadvertently killed.)

•

Signals are used internally by the implementation. On Linux 2.2 and later, the first three real-time signals are used (see also signal(7)). On older Linux kernels, SIGUSR1 and SIGUSR2 are used. Applications must avoid the use of whichever set of signals is employed by the implementation.

•

Threads do not share process IDs. (In effect, LinuxThreads threads are implemented as processes which share more information than usual, but which do not share a common process ID.) LinuxThreads threads (including the manager thread) are visible as separate processes using ps(1).

The LinuxThreads implementation deviates from the POSIX.1 specification in a number of ways, including the following:

•

Calls to getpid(2) return a different value in each thread.

•

Calls to getppid(2) in threads other than the main thread return the process ID of the manager thread; instead getppid(2) in these threads should return the same value as getppid(2) in the main thread.

•

When one thread creates a new child process using fork(2), any thread should be able to wait(2) on the child. However, the implementation allows only the thread that created the child to wait(2) on it.

•

When a thread calls execve(2), all other threads are terminated (as required by POSIX.1). However, the resulting process has the same PID as the thread that called execve(2): it should have the same PID as the main thread.

•

Threads do not share user and group IDs. This can cause complications with set-user-ID programs and can cause failures in Pthreads functions if an application changes its credentials using seteuid(2) or similar.

•

Threads do not share a common session ID and process group ID.

•

Threads do not share record locks created using fcntl(2).

•

The information returned by times(2) and getrusage(2) is per-thread rather than process-wide.

•

Threads do not share semaphore undo values (see semop(2)).

•

Threads do not share interval timers.

•

Threads do not share a common nice value.

•

POSIX.1 distinguishes the notions of signals that are directed to the process as a whole and signals that are directed to individual threads. According to POSIX.1, a process-directed signal (sent using kill(2), for example) should be handled by a single, arbitrarily selected thread within the process. LinuxThreads does not support the notion of process-directed signals: signals may be sent only to specific threads.

•

Threads have distinct alternate signal stack settings. However, a new thread's alternate signal stack settings are copied from the thread that created it, so that the threads initially share an alternate signal stack. (A new thread should start with no alternate signal stack defined. If two threads handle signals on their shared alternate signal stack at the same time, unpredictable program failures are likely to occur.)

### NPTL
With NPTL, all of the threads in a process are placed in the same thread group; all members of a thread group share the same PID. NPTL does not employ a manager thread.

NPTL makes internal use of the first two real-time signals; these signals cannot be used in applications. See nptl(7) for further details.

NPTL still has at least one nonconformance with POSIX.1:

•

Threads do not share a common nice value.

Some NPTL nonconformances occur only with older kernels:

•

The information returned by times(2) and getrusage(2) is per-thread rather than process-wide (fixed in Linux 2.6.9).

•

Threads do not share resource limits (fixed in Linux 2.6.10).

•

Threads do not share interval timers (fixed in Linux 2.6.12).

•

Only the main thread is permitted to start a new session using setsid(2) (fixed in Linux 2.6.16).

•

Only the main thread is permitted to make the process into a process group leader using setpgid(2) (fixed in Linux 2.6.16).

•

Threads have distinct alternate signal stack settings. However, a new thread's alternate signal stack settings are copied from the thread that created it, so that the threads initially share an alternate signal stack (fixed in Linux 2.6.16).

Note the following further points about the NPTL implementation:

•

If the stack size soft resource limit (see the description of RLIMIT_STACK in setrlimit(2)) is set to a value other than unlimited, then this value defines the default stack size for new threads. To be effective, this limit must be set before the program is executed, perhaps using the ulimit -s shell built-in command (limit stacksize in the C shell).

### Determining the threading implementation
Since glibc 2.3.2, the getconf(1) command can be used to determine the system's threading implementation, for example:

```
bash$ getconf GNU_LIBPTHREAD_VERSION
NPTL 2.3.4
```

With older glibc versions, a command such as the following should be sufficient to determine the default threading implementation:

```
bash$ $( ldd /bin/ls | grep libc.so | awk '{print $3}' ) | \

                egrep -i 'threads|nptl'

        Native POSIX Threads Library by Ulrich Drepper et al
```

### Selecting the threading implementation: LD_ASSUME_KERNEL
On systems with a glibc that supports both LinuxThreads and NPTL (i.e., glibc 2.3.x), the LD_ASSUME_KERNEL environment variable can be used to override the dynamic linker's default choice of threading implementation. This variable tells the dynamic linker to assume that it is running on top of a particular kernel version. By specifying a kernel version that does not provide the support required by NPTL, we can force the use of LinuxThreads. (The most likely reason for doing this is to run a (broken) application that depends on some nonconformant behavior in LinuxThreads.) For example:

```
bash$ $( LD_ASSUME_KERNEL=2.2.5 ldd /bin/ls | grep libc.so | \

                awk '{print $3}' ) | egrep -i 'threads|nptl'

        linuxthreads-0.10 by Xavier Leroy
```

## SEE ALSO
clone(2), fork(2), futex(2), gettid(2), proc(5), attributes(7), futex(7), nptl(7), sigevent(7), signal(7)

Various Pthreads manual pages, for example: pthread_atfork(3), pthread_attr_init(3), pthread_cancel(3), pthread_cleanup_push(3), pthread_cond_signal(3), pthread_cond_wait(3), pthread_create(3), pthread_detach(3), pthread_equal(3), pthread_exit(3), pthread_key_create(3), pthread_kill(3), pthread_mutex_lock(3), pthread_mutex_unlock(3), pthread_mutexattr_destroy(3), pthread_mutexattr_init(3), pthread_once(3), pthread_spin_init(3), pthread_spin_lock(3), pthread_rwlockattr_setkind_np(3), pthread_setcancelstate(3), pthread_setcanceltype(3), pthread_setspecific(3), pthread_sigmask(3), pthread_sigqueue(3), and pthread_testcancel(3)