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.

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.

In Linux versions before 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 write(2)s 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 kernel 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:

(1)

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.

(2)

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.

(3)

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

(a)

Test whether the user has exceeded the limit.

(b)

Make the new pipe buffer allocation.

(c)

Account new allocation against the limits.

This was racey. Multiple processes could pass point (a) simultaneously, and then allocate pipe buffers that were accounted for only in step (c), 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 (1) and (3) 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

package: man-pages

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/ 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 <unistd.h>
#include <sys/syscall.h>
#include <stdio.h>
#include <sys/mman.h>
static inline void
wrpkru(unsigned int pkru)
{

    unsigned int eax = pkru;

    unsigned int ecx = 0;

    unsigned int edx = 0;

    asm volatile(".byte 0x0f,0x01,0xef\n\t"

                 : : "a" (eax), "c" (ecx), "d" (edx));
}
int
pkey_set(int pkey, unsigned long rights, unsigned long flags)
{

    unsigned int pkru = (rights << (2 * pkey));

    return wrpkru(pkru);
}
int
pkey_mprotect(void *ptr, size_t size, unsigned long orig_prot,

              unsigned long pkey)
{

    return syscall(SYS_pkey_mprotect, ptr, size, orig_prot, pkey);
}
int
pkey_alloc(void)
{

    return syscall(SYS_pkey_alloc, 0, 0);
}
int
pkey_free(unsigned long pkey)
{

    return syscall(SYS_pkey_free, pkey);
}
#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \

                           } while (0)
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)

        errExit("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();

    if (pkey == -1)

        errExit("pkey_alloc");

    /*

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

     * even though there is none right now.

     */

    status = pkey_set(pkey, PKEY_DISABLE_ACCESS, 0);

    if (status)

        errExit("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)

        errExit("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)

        errExit("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()
getcwd()
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()
```

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

The following functions are required to be cancellation 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 cancellation 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 cancellation points. In particular, an implementation is likely to mark any nonstandard function that may block as a cancellation point. (This includes most functions that can touch files.)

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

### 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 kernel 2.6.9).

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

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

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

- Only the main thread is permitted to make the process into a process group leader using setpgid(2) (fixed in kernel 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 kernel 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)


pty

title: pty(7)

summary: pseudoterminal interfaces

text:
# pty(7)

## NAME
pty - pseudoterminal interfaces

## DESCRIPTION
A pseudoterminal (sometimes abbreviated "pty") is a pair of virtual character devices that provide a bidirectional communication channel. One end of the channel is called the master; the other end is called the slave.

The slave end of the pseudoterminal provides an interface that behaves exactly like a classical terminal. A process that expects to be connected to a terminal, can open the slave end of a pseudoterminal and then be driven by a program that has opened the master end. Anything that is written on the master end is provided to the process on the slave end as though it was input typed on a terminal. For example, writing the interrupt character (usually control-C) to the master device would cause an interrupt signal (SIGINT) to be generated for the foreground process group that is connected to the slave. Conversely, anything that is written to the slave end of the pseudoterminal can be read by the process that is connected to the master end.

Data flow between master and slave is handled asynchronously, much like data flow with a physical terminal. Data written to the slave will be available at the master promptly, but may not be available immediately. Similarly, there may be a small processing delay between a write to the master, and the effect being visible at the slave.

Historically, two pseudoterminal APIs have evolved: BSD and System V. SUSv1 standardized a pseudoterminal API based on the System V API, and this API should be employed in all new programs that use pseudoterminals.

Linux provides both BSD-style and (standardized) System V-style pseudoterminals. System V-style terminals are commonly called UNIX 98 pseudoterminals on Linux systems.

Since kernel 2.6.4, BSD-style pseudoterminals are considered deprecated: support can be disabled when building the kernel by disabling the CONFIG_LEGACY_PTYS option. (Starting with Linux 2.6.30, that option is disabled by default in the mainline kernel.) UNIX 98 pseudoterminals should be used in new applications.

### UNIX 98 pseudoterminals
An unused UNIX 98 pseudoterminal master is opened by calling posix_openpt(3). (This function opens the master clone device, /dev/ptmx; see pts(4).) After performing any program-specific initializations, changing the ownership and permissions of the slave device using grantpt(3), and unlocking the slave using unlockpt(3)), the corresponding slave device can be opened by passing the name returned by ptsname(3) in a call to open(2).

The Linux kernel imposes a limit on the number of available UNIX 98 pseudoterminals. In kernels up to and including 2.6.3, this limit is configured at kernel compilation time (CONFIG_UNIX98_PTYS), and the permitted number of pseudoterminals can be up to 2048, with a default setting of 256. Since kernel 2.6.4, the limit is dynamically adjustable via /proc/sys/kernel/pty/max, and a corresponding file, /proc/sys/kernel/pty/nr, indicates how many pseudoterminals are currently in use. For further details on these two files, see proc(5).

### BSD pseudoterminals
BSD-style pseudoterminals are provided as precreated pairs, with names of the form /dev/ptyXY (master) and /dev/ttyXY (slave), where X is a letter from the 16-character set [p-za-e], and Y is a letter from the 16-character set [0-9a-f]. (The precise range of letters in these two sets varies across UNIX implementations.) For example, /dev/ptyp1 and /dev/ttyp1 constitute a BSD pseudoterminal pair. A process finds an unused pseudoterminal pair by trying to open(2) each pseudoterminal master until an open succeeds. The corresponding pseudoterminal slave (substitute "tty" for "pty" in the name of the master) can then be opened.

## FILES
/dev/ptmx

UNIX 98 master clone device

/dev/pts/*

UNIX 98 slave devices

/dev/pty[p-za-e][0-9a-f]

BSD master devices

/dev/tty[p-za-e][0-9a-f]

BSD slave devices

## NOTES
Pseudoterminals are used by applications such as network login services (ssh(1), rlogin(1), telnet(1)), terminal emulators such as xterm(1), script(1), screen(1), tmux(1), unbuffer(1), and expect(1).

A description of the TIOCPKT ioctl(2), which controls packet mode operation, can be found in ioctl_tty(2).

The BSD ioctl(2) operations TIOCSTOP, TIOCSTART, TIOCUCNTL, and TIOCREMOTE have not been implemented under Linux.

## SEE ALSO
ioctl_tty(2), select(2), setsid(2), forkpty(3), openpty(3), termios(3), pts(4), tty(4)


queue

title: queue(7)

text:
# queue(7)

## NAME
queue - implementations of linked lists and queues

## DESCRIPTION
The <sys/queue.h> header file provides a set of macros that define and operate on the following data structures:

- singly linked lists (SLIST)

- doubly linked lists (LIST)

- singly linked tail queues (STAILQ)

- doubly linked tail queues (TAILQ)

- doubly linked circular queues (CIRCLEQ)

All structures support the following functionality:

- Insertion of a new entry at the head of the list.

- Insertion of a new entry after any element in the list.

- O(1) removal of an entry from the head of the list.

- Forward traversal through the list.

Code size and execution time depend on the complexity of the data structure being used, so programmers should take care to choose the appropriate one.

### Singly linked lists (SLIST)
Singly linked lists are the simplest and support only the above functionality. Singly linked lists are ideal for applications with large datasets and few or no removals, or for implementing a LIFO queue. Singly linked lists add the following functionality:

*

O(n) removal of any entry in the list.

### Singly linked tail queues (STAILQ)
Singly linked tail queues add the following functionality:

- Entries can be added at the end of a list.

- O(n) removal of any entry in the list.

- They may be concatenated.

However:

- All list insertions must specify the head of the list.

- Each head entry requires two pointers rather than one.

Singly linked tail queues are ideal for applications with large datasets and few or no removals, or for implementing a FIFO queue.

### Doubly linked data structures
All doubly linked types of data structures (lists and tail queues) additionally allow:

- Insertion of a new entry before any element in the list.

- O(1) removal of any entry in the list.

However:

*

Each element requires two pointers rather than one.

### Doubly linked lists (LIST)
Linked lists are the simplest of the doubly linked data structures. They add the following functionality over the above:

*

They may be traversed backwards.

However:

*

To traverse backwards, an entry to begin the traversal and the list in which it is contained must be specified.

### Doubly linked tail queues (TAILQ)
Tail queues add the following functionality:

- Entries can be added at the end of a list.

- They may be traversed backwards, from tail to head.

- They may be concatenated.

However:

- All list insertions and removals must specify the head of the list.

- Each head entry requires two pointers rather than one.

### Doubly linked circular queues (CIRCLEQ)
Circular queues add the following functionality over the above:

*

The first and last entries are connected.

However:

*

The termination condition for traversal is more complex.

## CONFORMING TO
Not in POSIX.1, POSIX.1-2001, or POSIX.1-2008. Present on the BSDs. <sys/queue.h> macros first appeared in 4.4BSD.

## NOTES
Some BSDs provide SIMPLEQ instead of STAILQ. They are identical, but for historical reasons they were named differently on different BSDs. STAILQ originated on FreeBSD, and SIMPLEQ originated on NetBSD. For compatibility reasons, some systems provide both sets of macros. Glibc provides both STAILQ and SIMPLEQ, which are identical except for a missing SIMPLEQ equivalent to STAILQ_CONCAT().

## SEE ALSO
circleq(3), insque(3), list(3), slist(3), stailq(3), tailq(3)


random

title: random(7)

text:
# random(7)

## NAME
random - overview of interfaces for obtaining randomness

## DESCRIPTION
The kernel random-number generator relies on entropy gathered from device drivers and other sources of environmental noise to seed a cryptographically secure pseudorandom number generator (CSPRNG). It is designed for security, rather than speed.

The following interfaces provide access to output from the kernel CSPRNG:

- The /dev/urandom and /dev/random devices, both described in random(4). These devices have been present on Linux since early times, and are also available on many other systems.

- The Linux-specific getrandom(2) system call, available since Linux 3.17. This system call provides access either to the same source as /dev/urandom (called the urandom source in this page) or to the same source as /dev/random (called the random source in this page). The default is the urandom source; the random source is selected by specifying the GRND_RANDOM flag to the system call. (The getentropy(3) function provides a slightly more portable interface on top of getrandom(2).)

### Initialization of the entropy pool
The kernel collects bits of entropy from the environment. When a sufficient number of random bits has been collected, the entropy pool is considered to be initialized.

### Choice of random source
Unless you are doing long-term key generation (and most likely not even then), you probably shouldn't be reading from the /dev/random device or employing getrandom(2) with the GRND_RANDOM flag. Instead, either read from the /dev/urandom device or employ getrandom(2) without the GRND_RANDOM flag. The cryptographic algorithms used for the urandom source are quite conservative, and so should be sufficient for all purposes.

The disadvantage of GRND_RANDOM and reads from /dev/random is that the operation can block for an indefinite period of time. Furthermore, dealing with the partially fulfilled requests that can occur when using GRND_RANDOM or when reading from /dev/random increases code complexity.

### Monte Carlo and other probabilistic sampling applications
Using these interfaces to provide large quantities of data for Monte Carlo simulations or other programs/algorithms which are doing probabilistic sampling will be slow. Furthermore, it is unnecessary, because such applications do not need cryptographically secure random numbers. Instead, use the interfaces described in this page to obtain a small amount of data to seed a user-space pseudorandom number generator for use by such applications.

### Comparison between getrandom, /dev/urandom, and /dev/random
The following table summarizes the behavior of the various interfaces that can be used to obtain randomness. GRND_NONBLOCK is a flag that can be used to control the blocking behavior of getrandom(2). The final column of the table considers the case that can occur in early boot time when the entropy pool is not yet initialized.

Interface

Pool

Blocking behavior

Behavior when pool is not yet ready

/dev/random

Blocking pool

If entropy too low, blocks until there is enough entropy again

Blocks until enough entropy gathered

/dev/urandom

CSPRNG output

Never blocks

Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography)

getrandom ()

Same as /dev/urandom

Does not block once is pool ready

Blocks until pool ready

getrandom () GRND_RANDOM

Same as /dev/random

If entropy too low, blocks until there is enough entropy again

Blocks until pool ready

getrandom () GRND_NONBLOCK

Same as /dev/urandom

Does not block once is pool ready

EAGAIN

getrandom () GRND_RANDOM + GRND_NONBLOCK

Same as /dev/random

EAGAIN if not enough entropy available

EAGAIN

### Generating cryptographic keys
The amount of seed material required to generate a cryptographic key equals the effective key size of the key. For example, a 3072-bit RSA or Diffie-Hellman private key has an effective key size of 128 bits (it requires about 2^128 operations to break) so a key generator needs only 128 bits (16 bytes) of seed material from /dev/random.

While some safety margin above that minimum is reasonable, as a guard against flaws in the CSPRNG algorithm, no cryptographic primitive available today can hope to promise more than 256 bits of security, so if any program reads more than 256 bits (32 bytes) from the kernel random pool per invocation, or per reasonable reseed interval (not less than one minute), that should be taken as a sign that its cryptography is not skillfully implemented.

## SEE ALSO
getrandom(2), getauxval(3), getentropy(3), random(4), urandom(4), signal(7)


raw

title: raw(7)

summary: Linux IPv4 raw sockets

text:
# raw(7)

## NAME
raw - Linux IPv4 raw sockets

## SYNOPSIS

```
#include <sys/socket.h>
#include <netinet/in.h>
raw_socket = socket(AF_INET, SOCK_RAW, int protocol);
```

## DESCRIPTION
Raw sockets allow new IPv4 protocols to be implemented in user space. A raw socket receives or sends the raw datagram not including link level headers.

The IPv4 layer generates an IP header when sending a packet unless the IP_HDRINCL socket option is enabled on the socket. When it is enabled, the packet must contain an IP header. For receiving, the IP header is always included in the packet.

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

All packets or errors matching the protocol number specified for the raw socket are passed to this socket. For a list of the allowed protocols, see the IANA list of assigned protocol numbers at http://www.iana.org/assignments/protocol-numbers/ and getprotobyname(3).

A protocol of IPPROTO_RAW implies enabled IP_HDRINCL and is able to send any IP protocol that is specified in the passed header. Receiving of all IP protocols via IPPROTO_RAW is not possible using raw sockets.

IP Header fields modified on sending by IP_HDRINCL

IP Checksum

Always filled in

Source Address

Filled in when zero

Packet ID

Filled in when zero

Total Length

Always filled in

If IP_HDRINCL is specified and the IP header has a nonzero destination address, then the destination address of the socket is used to route the packet. When MSG_DONTROUTE is specified, the destination address should refer to a local interface, otherwise a routing table lookup is done anyway but gatewayed routes are ignored.

If IP_HDRINCL isn't set, then IP header options can be set on raw sockets with setsockopt(2); see ip(7) for more information.

Starting with Linux 2.2, all IP header fields and options can be set using IP socket options. This means raw sockets are usually needed only for new protocols or protocols with no user interface (like ICMP).

When a packet is received, it is passed to any raw sockets which have been bound to its protocol before it is passed to other protocol handlers (e.g., kernel protocol modules).

### Address format
For sending and receiving datagrams (sendto(2), recvfrom(2), and similar), raw sockets use the standard sockaddr_in address structure defined in ip(7). The sin_port field could be used to specify the IP protocol number, but it is ignored for sending in Linux 2.2 and later, and should be always set to 0 (see BUGS). For incoming packets, sin_port is set to zero.

### Socket options
Raw socket options can be set with setsockopt(2) and read with getsockopt(2) by passing the IPPROTO_RAW family flag.

ICMP_FILTER

Enable a special filter for raw sockets bound to the IPPROTO_ICMP protocol. The value has a bit set for each ICMP message type which should be filtered out. The default is to filter no ICMP messages.

In addition, all ip(7) IPPROTO_IP socket options valid for datagram sockets are supported.

### Error handling
Errors originating from the network are passed to the user only when the socket is connected or the IP_RECVERR flag is enabled. For connected sockets, only EMSGSIZE and EPROTO are passed for compatibility. With IP_RECVERR, all network errors are saved in the error queue.

## ERRORS
EACCES

User tried to send to a broadcast address without having the broadcast flag set on the socket.

EFAULT

An invalid memory address was supplied.

EINVAL

Invalid argument.

EMSGSIZE

Packet too big. Either Path MTU Discovery is enabled (the IP_MTU_DISCOVER socket flag) or the packet size exceeds the maximum allowed IPv4 packet size of 64 kB.

EOPNOTSUPP

Invalid flag has been passed to a socket call (like MSG_OOB).

EPERM

The user doesn't have permission to open raw sockets. Only processes with an effective user ID of 0 or the CAP_NET_RAW attribute may do that.

EPROTO

An ICMP error has arrived reporting a parameter problem.

## VERSIONS
IP_RECVERR and ICMP_FILTER are new in Linux 2.2. They are Linux extensions and should not be used in portable programs.

Linux 2.0 enabled some bug-to-bug compatibility with BSD in the raw socket code when the SO_BSDCOMPAT socket option was set; since Linux 2.2, this option no longer has that effect.

## NOTES
By default, raw sockets do path MTU (Maximum Transmission Unit) discovery. This means the kernel will keep track of the MTU to a specific target IP address and return EMSGSIZE when a raw packet write exceeds it. When this happens, the application should decrease the packet size. Path MTU discovery can be also turned off using the IP_MTU_DISCOVER socket option or the /proc/sys/net/ipv4/ip_no_pmtu_disc file, see ip(7) for details. When turned off, raw sockets will fragment outgoing packets that exceed the interface MTU. However, disabling it is not recommended for performance and reliability reasons.

A raw socket can be bound to a specific local address using the bind(2) call. If it isn't bound, all packets with the specified IP protocol are received. In addition, a raw socket can be bound to a specific network device using SO_BINDTODEVICE; see socket(7).

An IPPROTO_RAW socket is send only. If you really want to receive all IP packets, use a packet(7) socket with the ETH_P_IP protocol. Note that packet sockets don't reassemble IP fragments, unlike raw sockets.

If you want to receive all ICMP packets for a datagram socket, it is often better to use IP_RECVERR on that particular socket; see ip(7).

Raw sockets may tap all IP protocols in Linux, even protocols like ICMP or TCP which have a protocol module in the kernel. In this case, the packets are passed to both the kernel module and the raw socket(s). This should not be relied upon in portable programs, many other BSD socket implementation have limitations here.

Linux never changes headers passed from the user (except for filling in some zeroed fields as described for IP_HDRINCL). This differs from many other implementations of raw sockets.

Raw sockets are generally rather unportable and should be avoided in programs intended to be portable.

Sending on raw sockets should take the IP protocol from sin_port; this ability was lost in Linux 2.2. The workaround is to use IP_HDRINCL.

## BUGS
Transparent proxy extensions are not described.

When the IP_HDRINCL option is set, datagrams will not be fragmented and are limited to the interface MTU.

Setting the IP protocol for sending in sin_port got lost in Linux 2.2. The protocol that the socket was bound to or that was specified in the initial socket(2) call is always used.

## SEE ALSO
recvmsg(2), sendmsg(2), capabilities(7), ip(7), socket(7)

RFC 1191 for path MTU discovery. RFC 791 and the <linux/ip.h> header file for the IP protocol.


regex

title: regex(7)

summary: POSIX.2 regular expressions

text:
# regex(7)

## NAME
regex - POSIX.2 regular expressions

## DESCRIPTION
Regular expressions ("RE"s), as defined in POSIX.2, come in two forms: modern REs (roughly those of egrep; POSIX.2 calls these "extended" REs) and obsolete REs (roughly those of ed(1); POSIX.2 "basic" REs). Obsolete REs mostly exist for backward compatibility in some old programs; they will be discussed at the end. POSIX.2 leaves some aspects of RE syntax and semantics open; "(!)" marks decisions on these aspects that may not be fully portable to other POSIX.2 implementations.

A (modern) RE is one(!) or more nonempty(!) branches, separated by '|'. It matches anything that matches one of the branches.

A branch is one(!) or more pieces, concatenated. It matches a match for the first, followed by a match for the second, and so on.

A piece is an atom possibly followed by a single(!) '*', '+', '?', or bound. An atom followed by '*' matches a sequence of 0 or more matches of the atom. An atom followed by '+' matches a sequence of 1 or more matches of the atom. An atom followed by '?' matches a sequence of 0 or 1 matches of the atom.

A bound is '{' followed by an unsigned decimal integer, possibly followed by ',' possibly followed by another unsigned decimal integer, always followed by '}'. The integers must lie between 0 and RE_DUP_MAX (255(!)) inclusive, and if there are two of them, the first may not exceed the second. An atom followed by a bound containing one integer i and no comma matches a sequence of exactly i matches of the atom. An atom followed by a bound containing one integer i and a comma matches a sequence of i or more matches of the atom. An atom followed by a bound containing two integers i and j matches a sequence of i through j (inclusive) matches of the atom.

An atom is a regular expression enclosed in "()" (matching a match for the regular expression), an empty set of "()" (matching the null string)(!), a bracket expression (see below), '.' (matching any single character), '^' (matching the null string at the beginning of a line), '$' (matching the null string at the end of a line), a '\' followed by one of the characters "^.[$()|*+?{\" (matching that character taken as an ordinary character), a '\' followed by any other character(!) (matching that character taken as an ordinary character, as if the '\' had not been present(!)), or a single character with no other significance (matching that character). A '{' followed by a character other than a digit is an ordinary character, not the beginning of a bound(!). It is illegal to end an RE with '\'.

A bracket expression is a list of characters enclosed in "[]". It normally matches any single character from the list (but see below). If the list begins with '^', it matches any single character (but see below) not from the rest of the list. If two characters in the list are separated by '-', this is shorthand for the full range of characters between those two (inclusive) in the collating sequence, for example, "[0-9]" in ASCII matches any decimal digit. It is illegal(!) for two ranges to share an endpoint, for example, "a-c-e". Ranges are very collating-sequence-dependent, and portable programs should avoid relying on them.

To include a literal ']' in the list, make it the first character (following a possible '^'). To include a literal '-', make it the first or last character, or the second endpoint of a range. To use a literal '-' as the first endpoint of a range, enclose it in "[." and ".]" to make it a collating element (see below). With the exception of these and some combinations using '[' (see next paragraphs), all other special characters, including '\', lose their special significance within a bracket expression.

Within a bracket expression, a collating element (a character, a multicharacter sequence that collates as if it were a single character, or a collating-sequence name for either) enclosed in "[." and ".]" stands for the sequence of characters of that collating element. The sequence is a single element of the bracket expression's list. A bracket expression containing a multicharacter collating element can thus match more than one character, for example, if the collating sequence includes a "ch" collating element, then the RE "[[.ch.]]*c" matches the first five characters of "chchcc".

Within a bracket expression, a collating element enclosed in "[=" and "=]" is an equivalence class, standing for the sequences of characters of all collating elements equivalent to that one, including itself. (If there are no other equivalent collating elements, the treatment is as if the enclosing delimiters were "[." and ".]".) For example, if o and a are the members of an equivalence class, then "[[=o=]]", "[[=a=]]", and "[oa]" are all synonymous. An equivalence class may not(!) be an endpoint of a range.

Within a bracket expression, the name of a character class enclosed in "[:" and ":]" stands for the list of all characters belonging to that class. Standard character class names are:

alnum

digit

punct

alpha

graph

space

blank

lower

upper

cntrl

print

xdigit

These stand for the character classes defined in wctype(3). A locale may provide others. A character class may not be used as an endpoint of a range.

In the event that an RE could match more than one substring of a given string, the RE matches the one starting earliest in the string. If the RE could match more than one substring starting at that point, it matches the longest. Subexpressions also match the longest possible substrings, subject to the constraint that the whole match be as long as possible, with subexpressions starting earlier in the RE taking priority over ones starting later. Note that higher-level subexpressions thus take priority over their lower-level component subexpressions.

Match lengths are measured in characters, not collating elements. A null string is considered longer than no match at all. For example, "bb*" matches the three middle characters of "abbbc", "(wee|week)(knights|nights)" matches all ten characters of "weeknights", when "(.*).*" is matched against "abc" the parenthesized subexpression matches all three characters, and when "(a*)*" is matched against "bc" both the whole RE and the parenthesized subexpression match the null string.

If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. When an alphabetic that exists in multiple cases appears as an ordinary character outside a bracket expression, it is effectively transformed into a bracket expression containing both cases, for example, 'x' becomes "[xX]". When it appears inside a bracket expression, all case counterparts of it are added to the bracket expression, so that, for example, "[x]" becomes "[xX]" and "[^x]" becomes "[^xX]".

No particular limit is imposed on the length of REs(!). Programs intended to be portable should not employ REs longer than 256 bytes, as an implementation can refuse to accept such REs and remain POSIX-compliant.

Obsolete ("basic") regular expressions differ in several respects. '|', '+', and '?' are ordinary characters and there is no equivalent for their functionality. The delimiters for bounds are "\{" and "\}", with '{' and '}' by themselves ordinary characters. The parentheses for nested subexpressions are "\(" and "\)", with '(' and ')' by themselves ordinary characters. '^' is an ordinary character except at the beginning of the RE or(!) the beginning of a parenthesized subexpression, '$' is an ordinary character except at the end of the RE or(!) the end of a parenthesized subexpression, and '*' is an ordinary character if it appears at the beginning of the RE or the beginning of a parenthesized subexpression (after a possible leading '^').

Finally, there is one new type of atom, a back reference: '\' followed by a nonzero decimal digit d matches the same sequence of characters matched by the dth parenthesized subexpression (numbering subexpressions by the positions of their opening parentheses, left to right), so that, for example, "\([bc]\)\1" matches "bb" or "cc" but not "bc".

## BUGS
Having two kinds of REs is a botch.

The current POSIX.2 spec says that ')' is an ordinary character in the absence of an unmatched '('; this was an unintentional result of a wording error, and change is likely. Avoid relying on it.

Back references are a dreadful botch, posing major problems for efficient implementations. They are also somewhat vaguely defined (does "a\(\(b\)*\2\)*d" match "abbbd"?). Avoid using them.

POSIX.2's specification of case-independent matching is vague. The "one case implies all cases" definition given above is current consensus among implementors as to the right interpretation.

## AUTHOR
This page was taken from Henry Spencer's regex package.

## SEE ALSO
grep(1), regex(3)

POSIX.2, section 2.8 (Regular Expression Notation).