title: user_namespaces(7)

summary: overview of Linux user namespaces

text:
# user_namespaces(7)

## NAME
user_namespaces - overview of Linux user namespaces

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

User namespaces isolate security-related identifiers and attributes, in particular, user IDs and group IDs (see credentials(7)), the root directory, keys (see keyrings(7)), and capabilities (see capabilities(7)). A process's user and group IDs can be different inside and outside a user namespace. In particular, a process can have a normal unprivileged user ID outside a user namespace while at the same time having a user ID of 0 inside the namespace; in other words, the process has full privileges for operations inside the user namespace, but is unprivileged for operations outside the namespace.

### Nested namespaces, namespace membership
User namespaces can be nested; that is, each user namespace—except the initial ("root") namespace—has a parent user namespace, and can have zero or more child user namespaces. The parent user namespace is the user namespace of the process that creates the user namespace via a call to unshare(2) or clone(2) with the CLONE_NEWUSER flag.

The kernel imposes (since version 3.11) a limit of 32 nested levels of user namespaces. Calls to unshare(2) or clone(2) that would cause this limit to be exceeded fail with the error EUSERS.

Each process is a member of exactly one user namespace. A process created via fork(2) or clone(2) without the CLONE_NEWUSER flag is a member of the same user namespace as its parent. A single-threaded process can join another user namespace with setns(2) if it has the CAP_SYS_ADMIN in that namespace; upon doing so, it gains a full set of capabilities in that namespace.

A call to clone(2) or unshare(2) with the CLONE_NEWUSER flag makes the new child process (for clone(2)) or the caller (for unshare(2)) a member of the new user namespace created by the call.

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

### Capabilities
The child process created by clone(2) with the CLONE_NEWUSER flag starts out with a complete set of capabilities in the new user namespace. Likewise, a process that creates a new user namespace using unshare(2) or joins an existing user namespace using setns(2) gains a full set of capabilities in that namespace. On the other hand, that process has no capabilities in the parent (in the case of clone(2)) or previous (in the case of unshare(2) and setns(2)) user namespace, even if the new namespace is created or joined by the root user (i.e., a process with user ID 0 in the root namespace).

Note that a call to execve(2) will cause a process's capabilities to be recalculated in the usual way (see capabilities(7)). Consequently, unless the process has a user ID of 0 within the namespace, or the executable file has a nonempty inheritable capabilities mask, the process will lose all capabilities. See the discussion of user and group ID mappings, below.

A call to clone(2) or unshare(2) using the CLONE_NEWUSER flag or a call to setns(2) that moves the caller into another user namespace sets the "securebits" flags (see capabilities(7)) to their default values (all flags disabled) in the child (for clone(2)) or caller (for unshare(2) or setns(2)). Note that because the caller no longer has capabilities in its original user namespace after a call to setns(2), it is not possible for a process to reset its "securebits" flags while retaining its user namespace membership by using a pair of setns(2) calls to move to another user namespace and then return to its original user namespace.

The rules for determining whether or not a process has a capability in a particular user namespace are as follows:

1.

A process has a capability inside a user namespace if it is a member of that namespace and it has the capability in its effective capability set. A process can gain capabilities in its effective capability set in various ways. For example, it may execute a set-user-ID program or an executable with associated file capabilities. In addition, a process may gain capabilities via the effect of clone(2), unshare(2), or setns(2), as already described.

2.

If a process has a capability in a user namespace, then it has that capability in all child (and further removed descendant) namespaces as well.

3.

When a user namespace is created, the kernel records the effective user ID of the creating process as being the "owner" of the namespace. A process that resides in the parent of the user namespace and whose effective user ID matches the owner of the namespace has all capabilities in the namespace. By virtue of the previous rule, this means that the process has all capabilities in all further removed descendant user namespaces as well. The NS_GET_OWNER_UID ioctl(2) operation can be used to discover the user ID of the owner of the namespace; see ioctl_ns(2).

### Effect of capabilities within a user namespace
Having a capability inside a user namespace permits a process to perform operations (that require privilege) only on resources governed by that namespace. In other words, having a capability in a user namespace permits a process to perform privileged operations on resources that are governed by (nonuser) namespaces owned by (associated with) the user namespace (see the next subsection).

On the other hand, there are many privileged operations that affect resources that are not associated with any namespace type, for example, changing the system (i.e., calendar) time (governed by CAP_SYS_TIME), loading a kernel module (governed by CAP_SYS_MODULE), and creating a device (governed by CAP_MKNOD). Only a process with privileges in the initial user namespace can perform such operations.

Holding CAP_SYS_ADMIN within the user namespace that owns a process's mount namespace allows that process to create bind mounts and mount the following types of filesystems:

- /proc (since Linux 3.8)

- /sys (since Linux 3.8)

- devpts (since Linux 3.9)

- tmpfs(5) (since Linux 3.9)

- ramfs (since Linux 3.9)

- mqueue (since Linux 3.9)

- bpf (since Linux 4.4)

- overlayfs (since Linux 5.11)

Holding CAP_SYS_ADMIN within the user namespace that owns a process's cgroup namespace allows (since Linux 4.6) that process to the mount the cgroup version 2 filesystem and cgroup version 1 named hierarchies (i.e., cgroup filesystems mounted with the "none,name=" option).

Holding CAP_SYS_ADMIN within the user namespace that owns a process's PID namespace allows (since Linux 3.8) that process to mount /proc filesystems.

Note however, that mounting block-based filesystems can be done only by a process that holds CAP_SYS_ADMIN in the initial user namespace.

### Interaction of user namespaces and other types of namespaces
Starting in Linux 3.8, unprivileged processes can create user namespaces, and the other types of namespaces can be created with just the CAP_SYS_ADMIN capability in the caller's user namespace.

When a nonuser namespace is created, it is owned by the user namespace in which the creating process was a member at the time of the creation of the namespace. Privileged operations on resources governed by the nonuser namespace require that the process has the necessary capabilities in the user namespace that owns the nonuser namespace.

If CLONE_NEWUSER is specified along with other CLONE_NEW* flags in a single clone(2) or unshare(2) call, the user namespace is guaranteed to be created first, giving the child (clone(2)) or caller (unshare(2)) privileges over the remaining namespaces created by the call. Thus, it is possible for an unprivileged caller to specify this combination of flags.

When a new namespace (other than a user namespace) is created via clone(2) or unshare(2), the kernel records the user namespace of the creating process as the owner of the new namespace. (This association can't be changed.) When a process in the new namespace subsequently performs privileged operations that operate on global resources isolated by the namespace, the permission checks are performed according to the process's capabilities in the user namespace that the kernel associated with the new namespace. For example, suppose that a process attempts to change the hostname (sethostname(2)), a resource governed by the UTS namespace. In this case, the kernel will determine which user namespace owns the process's UTS namespace, and check whether the process has the required capability (CAP_SYS_ADMIN) in that user namespace.

The NS_GET_USERNS ioctl(2) operation can be used to discover the user namespace that owns a nonuser namespace; see ioctl_ns(2).

### User and group ID mappings: uid_map and gid_map
When a user namespace is created, it starts out without a mapping of user IDs (group IDs) to the parent user namespace. The /proc/[pid]/uid_map and /proc/[pid]/gid_map files (available since Linux 3.5) expose the mappings for user and group IDs inside the user namespace for the process pid. These files can be read to view the mappings in a user namespace and written to (once) to define the mappings.

The description in the following paragraphs explains the details for uid_map; gid_map is exactly the same, but each instance of "user ID" is replaced by "group ID".

The uid_map file exposes the mapping of user IDs from the user namespace of the process pid to the user namespace of the process that opened uid_map (but see a qualification to this point below). In other words, processes that are in different user namespaces will potentially see different values when reading from a particular uid_map file, depending on the user ID mappings for the user namespaces of the reading processes.

Each line in the uid_map file specifies a 1-to-1 mapping of a range of contiguous user IDs between two user namespaces. (When a user namespace is first created, this file is empty.) The specification in each line takes the form of three numbers delimited by white space. The first two numbers specify the starting user ID in each of the two user namespaces. The third number specifies the length of the mapped range. In detail, the fields are interpreted as follows:

(1)

The start of the range of user IDs in the user namespace of the process pid.

(2)

The start of the range of user IDs to which the user IDs specified by field one map. How field two is interpreted depends on whether the process that opened uid_map and the process pid are in the same user namespace, as follows:

a)

If the two processes are in different user namespaces: field two is the start of a range of user IDs in the user namespace of the process that opened uid_map.

b)

If the two processes are in the same user namespace: field two is the start of the range of user IDs in the parent user namespace of the process pid. This case enables the opener of uid_map (the common case here is opening /proc/self/uid_map) to see the mapping of user IDs into the user namespace of the process that created this user namespace.

(3)

The length of the range of user IDs that is mapped between the two user namespaces.

System calls that return user IDs (group IDs)—for example, getuid(2), getgid(2), and the credential fields in the structure returned by stat(2)—return the user ID (group ID) mapped into the caller's user namespace.

When a process accesses a file, its user and group IDs are mapped into the initial user namespace for the purpose of permission checking and assigning IDs when creating a file. When a process retrieves file user and group IDs via stat(2), the IDs are mapped in the opposite direction, to produce values relative to the process user and group ID mappings.

The initial user namespace has no parent namespace, but, for consistency, the kernel provides dummy user and group ID mapping files for this namespace. Looking at the uid_map file (gid_map is the same) from a shell in the initial namespace shows:

```
$ cat /proc/$$/uid_map

         0          0 4294967295
```

This mapping tells us that the range starting at user ID 0 in this namespace maps to a range starting at 0 in the (nonexistent) parent namespace, and the length of the range is the largest 32-bit unsigned integer. This leaves 4294967295 (the 32-bit signed -1 value) unmapped. This is deliberate: (uid_t) -1 is used in several interfaces (e.g., setreuid(2)) as a way to specify "no user ID". Leaving (uid_t) -1 unmapped and unusable guarantees that there will be no confusion when using these interfaces.

### Defining user and group ID mappings: writing to uid_map and gid_map
After the creation of a new user namespace, the uid_map file of one of the processes in the namespace may be written to once to define the mapping of user IDs in the new user namespace. An attempt to write more than once to a uid_map file in a user namespace fails with the error EPERM. Similar rules apply for gid_map files.

The lines written to uid_map (gid_map) must conform to the following rules:

- The three fields must be valid numbers, and the last field must be greater than 0.

- Lines are terminated by newline characters.

- There is a limit on the number of lines in the file. In Linux 4.14 and earlier, this limit was (arbitrarily) set at 5 lines. Since Linux 4.15, the limit is 340 lines. In addition, the number of bytes written to the file must be less than the system page size, and the write must be performed at the start of the file (i.e., lseek(2) and pwrite(2) can't be used to write to nonzero offsets in the file).

- The range of user IDs (group IDs) specified in each line cannot overlap with the ranges in any other lines. In the initial implementation (Linux 3.8), this requirement was satisfied by a simplistic implementation that imposed the further requirement that the values in both field 1 and field 2 of successive lines must be in ascending numerical order, which prevented some otherwise valid maps from being created. Linux 3.9 and later fix this limitation, allowing any valid set of nonoverlapping maps.

- At least one line must be written to the file.

Writes that violate the above rules fail with the error EINVAL.

In order for a process to write to the /proc/[pid]/uid_map (/proc/[pid]/gid_map) file, all of the following requirements must be met:

1.

The writing process must have the CAP_SETUID (CAP_SETGID) capability in the user namespace of the process pid.

2.

The writing process must either be in the user namespace of the process pid or be in the parent user namespace of the process pid.

3.

The mapped user IDs (group IDs) must in turn have a mapping in the parent user namespace.

4.

One of the following two cases applies:

*

Either the writing process has the CAP_SETUID (CAP_SETGID) capability in the parent user namespace.

+

No further restrictions apply: the process can make mappings to arbitrary user IDs (group IDs) in the parent user namespace.

*

Or otherwise all of the following restrictions apply:

+

The data written to uid_map (gid_map) must consist of a single line that maps the writing process's effective user ID (group ID) in the parent user namespace to a user ID (group ID) in the user namespace.

+

The writing process must have the same effective user ID as the process that created the user namespace.

+

In the case of gid_map, use of the setgroups(2) system call must first be denied by writing "deny" to the /proc/[pid]/setgroups file (see below) before writing to gid_map.

Writes that violate the above rules fail with the error EPERM.

### Interaction with system calls that change process UIDs or GIDs
In a user namespace where the uid_map file has not been written, the system calls that change user IDs will fail. Similarly, if the gid_map file has not been written, the system calls that change group IDs will fail. After the uid_map and gid_map files have been written, only the mapped values may be used in system calls that change user and group IDs.

For user IDs, the relevant system calls include setuid(2), setfsuid(2), setreuid(2), and setresuid(2). For group IDs, the relevant system calls include setgid(2), setfsgid(2), setregid(2), setresgid(2), and setgroups(2).

Writing "deny" to the /proc/[pid]/setgroups file before writing to /proc/[pid]/gid_map will permanently disable setgroups(2) in a user namespace and allow writing to /proc/[pid]/gid_map without having the CAP_SETGID capability in the parent user namespace.

### The /proc/[pid]/setgroups file
The /proc/[pid]/setgroups file displays the string "allow" if processes in the user namespace that contains the process pid are permitted to employ the setgroups(2) system call; it displays "deny" if setgroups(2) is not permitted in that user namespace. Note that regardless of the value in the /proc/[pid]/setgroups file (and regardless of the process's capabilities), calls to setgroups(2) are also not permitted if /proc/[pid]/gid_map has not yet been set.

A privileged process (one with the CAP_SYS_ADMIN capability in the namespace) may write either of the strings "allow" or "deny" to this file before writing a group ID mapping for this user namespace to the file /proc/[pid]/gid_map. Writing the string "deny" prevents any process in the user namespace from employing setgroups(2).

The essence of the restrictions described in the preceding paragraph is that it is permitted to write to /proc/[pid]/setgroups only so long as calling setgroups(2) is disallowed because /proc/[pid]/gid_map has not been set. This ensures that a process cannot transition from a state where setgroups(2) is allowed to a state where setgroups(2) is denied; a process can transition only from setgroups(2) being disallowed to setgroups(2) being allowed.

The default value of this file in the initial user namespace is "allow".

Once /proc/[pid]/gid_map has been written to (which has the effect of enabling setgroups(2) in the user namespace), it is no longer possible to disallow setgroups(2) by writing "deny" to /proc/[pid]/setgroups (the write fails with the error EPERM).

A child user namespace inherits the /proc/[pid]/setgroups setting from its parent.

If the setgroups file has the value "deny", then the setgroups(2) system call can't subsequently be reenabled (by writing "allow" to the file) in this user namespace. (Attempts to do so fail with the error EPERM.) This restriction also propagates down to all child user namespaces of this user namespace.

The /proc/[pid]/setgroups file was added in Linux 3.19, but was backported to many earlier stable kernel series, because it addresses a security issue. The issue concerned files with permissions such as "rwx---rwx". Such files give fewer permissions to "group" than they do to "other". This means that dropping groups using setgroups(2) might allow a process file access that it did not formerly have. Before the existence of user namespaces this was not a concern, since only a privileged process (one with the CAP_SETGID capability) could call setgroups(2). However, with the introduction of user namespaces, it became possible for an unprivileged process to create a new namespace in which the user had all privileges. This then allowed formerly unprivileged users to drop groups and thus gain file access that they did not previously have. The /proc/[pid]/setgroups file was added to address this security issue, by denying any pathway for an unprivileged process to drop groups with setgroups(2).

### Unmapped user and group IDs
There are various places where an unmapped user ID (group ID) may be exposed to user space. For example, the first process in a new user namespace may call getuid(2) before a user ID mapping has been defined for the namespace. In most such cases, an unmapped user ID is converted to the overflow user ID (group ID); the default value for the overflow user ID (group ID) is 65534. See the descriptions of /proc/sys/kernel/overflowuid and /proc/sys/kernel/overflowgid in proc(5).

The cases where unmapped IDs are mapped in this fashion include system calls that return user IDs (getuid(2), getgid(2), and similar), credentials passed over a UNIX domain socket, credentials returned by stat(2), waitid(2), and the System V IPC "ctl" IPC_STAT operations, credentials exposed by /proc/[pid]/status and the files in /proc/sysvipc/*, credentials returned via the si_uid field in the siginfo_t received with a signal (see sigaction(2)), credentials written to the process accounting file (see acct(5)), and credentials returned with POSIX message queue notifications (see mq_notify(3)).

There is one notable case where unmapped user and group IDs are not converted to the corresponding overflow ID value. When viewing a uid_map or gid_map file in which there is no mapping for the second field, that field is displayed as 4294967295 (-1 as an unsigned integer).

### Accessing files
In order to determine permissions when an unprivileged process accesses a file, the process credentials (UID, GID) and the file credentials are in effect mapped back to what they would be in the initial user namespace and then compared to determine the permissions that the process has on the file. The same is also of other objects that employ the credentials plus permissions mask accessibility model, such as System V IPC objects

### Operation of file-related capabilities
Certain capabilities allow a process to bypass various kernel-enforced restrictions when performing operations on files owned by other users or groups. These capabilities are: CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER, and CAP_FSETID.

Within a user namespace, these capabilities allow a process to bypass the rules if the process has the relevant capability over the file, meaning that:

- the process has the relevant effective capability in its user namespace; and

- the file's user ID and group ID both have valid mappings in the user namespace.

The CAP_FOWNER capability is treated somewhat exceptionally: it allows a process to bypass the corresponding rules so long as at least the file's user ID has a mapping in the user namespace (i.e., the file's group ID does not need to have a valid mapping).

### Set-user-ID and set-group-ID programs
When a process inside a user namespace executes a set-user-ID (set-group-ID) program, the process's effective user (group) ID inside the namespace is changed to whatever value is mapped for the user (group) ID of the file. However, if either the user or the group ID of the file has no mapping inside the namespace, the set-user-ID (set-group-ID) bit is silently ignored: the new program is executed, but the process's effective user (group) ID is left unchanged. (This mirrors the semantics of executing a set-user-ID or set-group-ID program that resides on a filesystem that was mounted with the MS_NOSUID flag, as described in mount(2).)

### Miscellaneous
When a process's user and group IDs are passed over a UNIX domain socket to a process in a different user namespace (see the description of SCM_CREDENTIALS in unix(7)), they are translated into the corresponding values as per the receiving process's user and group ID mappings.

## CONFORMING TO
Namespaces are a Linux-specific feature.

## NOTES
Over the years, there have been a lot of features that have been added to the Linux kernel that have been made available only to privileged users because of their potential to confuse set-user-ID-root applications. In general, it becomes safe to allow the root user in a user namespace to use those features because it is impossible, while in a user namespace, to gain more privilege than the root user of a user namespace has.

### Availability
Use of user namespaces requires a kernel that is configured with the CONFIG_USER_NS option. User namespaces require support in a range of subsystems across the kernel. When an unsupported subsystem is configured into the kernel, it is not possible to configure user namespaces support.

As at Linux 3.8, most relevant subsystems supported user namespaces, but a number of filesystems did not have the infrastructure needed to map user and group IDs between user namespaces. Linux 3.9 added the required infrastructure support for many of the remaining unsupported filesystems (Plan 9 (9P), Andrew File System (AFS), Ceph, CIFS, CODA, NFS, and OCFS2). Linux 3.12 added support for the last of the unsupported major filesystems, XFS.

## EXAMPLES
The program below is designed to allow experimenting with user namespaces, as well as other types of namespaces. It creates namespaces as specified by command-line options and then executes a command inside those namespaces. The comments and usage() function inside the program provide a full explanation of the program. The following shell session demonstrates its use.

First, we look at the run-time environment:

```
$ uname -rs     # Need Linux 3.8 or later
Linux 3.8.0
$ id -u         # Running as unprivileged user
1000
$ id -g
1000
```

Now start a new shell in new user (-U), mount (-m), and PID (-p) namespaces, with user ID (-M) and group ID (-G) 1000 mapped to 0 inside the user namespace:

```
$ ./userns_child_exec -p -m -U -M '0 1000 1' -G '0 1000 1' bash
```

The shell has PID 1, because it is the first process in the new PID namespace:

```
bash$ echo $$
1
```

Mounting a new /proc filesystem and listing all of the processes visible in the new PID namespace shows that the shell can't see any processes outside the PID namespace:

```
bash$ mount -t proc proc /proc
bash$ ps ax

  PID TTY      STAT   TIME COMMAND

    1 pts/3    S      0:00 bash

   22 pts/3    R+     0:00 ps ax
```

Inside the user namespace, the shell has user and group ID 0, and a full set of permitted and effective capabilities:

```
bash$ cat /proc/$$/status | egrep '^[UG]id'
Uid:	0	0	0	0
Gid:	0	0	0	0
bash$ cat /proc/$$/status | egrep '^Cap(Prm|Inh|Eff)'
CapInh:	0000000000000000
CapPrm:	0000001fffffffff
CapEff:	0000001fffffffff
```

### Program source

```
/* userns_child_exec.c

   Licensed under GNU General Public License v2 or later

   Create a child process that executes a shell command in new

   namespace(s); allow UID and GID mappings to be specified when

   creating a user namespace.
*/
#define _GNU_SOURCE
#include <sched.h>
#include <unistd.h>
#include <stdint.h>
#include <stdlib.h>
#include <sys/wait.h>
#include <signal.h>
#include <fcntl.h>
#include <stdio.h>
#include <string.h>
#include <limits.h>
#include <errno.h>
/* A simple error-handling function: print an error message based

   on the value in 'errno' and terminate the calling process. */
#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \

                        } while (0)
struct child_args {

    char **argv;        /* Command to be executed by child, with args */

    int    pipe_fd[2];  /* Pipe used to synchronize parent and child */
};
static int verbose;
static void
usage(char *pname)
{

    fprintf(stderr, "Usage: %s [options] cmd [arg...]\n\n", pname);

    fprintf(stderr, "Create a child process that executes a shell "

            "command in a new user namespace,\n"

            "and possibly also other new namespace(s).\n\n");

    fprintf(stderr, "Options can be:\n\n");
#define fpe(str) fprintf(stderr, "    %s", str);

    fpe("-i          New IPC namespace\n");

    fpe("-m          New mount namespace\n");

    fpe("-n          New network namespace\n");

    fpe("-p          New PID namespace\n");

    fpe("-u          New UTS namespace\n");

    fpe("-U          New user namespace\n");

    fpe("-M uid_map  Specify UID map for user namespace\n");

    fpe("-G gid_map  Specify GID map for user namespace\n");

    fpe("-z          Map user's UID and GID to 0 in user namespace\n");

    fpe("            (equivalent to: -M '0 <uid> 1' -G '0 <gid> 1')\n");

    fpe("-v          Display verbose messages\n");

    fpe("\n");

    fpe("If -z, -M, or -G is specified, -U is required.\n");

    fpe("It is not permitted to specify both -z and either -M or -G.\n");

    fpe("\n");

    fpe("Map strings for -M and -G consist of records of the form:\n");

    fpe("\n");

    fpe("    ID-inside-ns   ID-outside-ns   len\n");

    fpe("\n");

    fpe("A map string can contain multiple records, separated"

        " by commas;\n");

    fpe("the commas are replaced by newlines before writing"

        " to map files.\n");

    exit(EXIT_FAILURE);
}
/* Update the mapping file 'map_file', with the value provided in

   'mapping', a string that defines a UID or GID mapping. A UID or

   GID mapping consists of one or more newline-delimited records

   of the form:

       ID_inside-ns    ID-outside-ns   length

   Requiring the user to supply a string that contains newlines is

   of course inconvenient for command-line use. Thus, we permit the

   use of commas to delimit records in this string, and replace them

   with newlines before writing the string to the file. */
static void
update_map(char *mapping, char *map_file)
{

    int fd;

    size_t map_len;     /* Length of 'mapping' */

    /* Replace commas in mapping string with newlines. */

    map_len = strlen(mapping);

    for (int j = 0; j < map_len; j++)

        if (mapping[j] == ',')

            mapping[j] = '\n';

    fd = open(map_file, O_RDWR);

    if (fd == -1) {

        fprintf(stderr, "ERROR: open %s: %s\n", map_file,

                strerror(errno));

        exit(EXIT_FAILURE);

    }

    if (write(fd, mapping, map_len) != map_len) {

        fprintf(stderr, "ERROR: write %s: %s\n", map_file,

                strerror(errno));

        exit(EXIT_FAILURE);

    }

    close(fd);
}
/* Linux 3.19 made a change in the handling of setgroups(2) and the

   'gid_map' file to address a security issue. The issue allowed

   *unprivileged* users to employ user namespaces in order to drop

   The upshot of the 3.19 changes is that in order to update the

   'gid_maps' file, use of the setgroups() system call in this

   user namespace must first be disabled by writing "deny" to one of

   the /proc/PID/setgroups files for this namespace.  That is the

   purpose of the following function. */
static void
proc_setgroups_write(pid_t child_pid, char *str)
{

    char setgroups_path[PATH_MAX];

    int fd;

    snprintf(setgroups_path, PATH_MAX, "/proc/%jd/setgroups",

            (intmax_t) child_pid);

    fd = open(setgroups_path, O_RDWR);

    if (fd == -1) {

        /* We may be on a system that doesn't support

           /proc/PID/setgroups. In that case, the file won't exist,

           and the system won't impose the restrictions that Linux 3.19

           added. That's fine: we don't need to do anything in order

           to permit 'gid_map' to be updated.

           However, if the error from open() was something other than

           the ENOENT error that is expected for that case,  let the

           user know. */

        if (errno != ENOENT)

            fprintf(stderr, "ERROR: open %s: %s\n", setgroups_path,

                strerror(errno));

        return;

    }

    if (write(fd, str, strlen(str)) == -1)

        fprintf(stderr, "ERROR: write %s: %s\n", setgroups_path,

            strerror(errno));

    close(fd);
}
static int              /* Start function for cloned child */
childFunc(void *arg)
{

    struct child_args *args = arg;

    char ch;

    /* Wait until the parent has updated the UID and GID mappings.

       See the comment in main(). We wait for end of file on a

       pipe that will be closed by the parent process once it has

       updated the mappings. */

    close(args->pipe_fd[1]);    /* Close our descriptor for the write

                                   end of the pipe so that we see EOF

                                   when parent closes its descriptor. */

    if (read(args->pipe_fd[0], &ch, 1) != 0) {

        fprintf(stderr,

                "Failure in child: read from pipe returned != 0\n");

        exit(EXIT_FAILURE);

    }

    close(args->pipe_fd[0]);

    /* Execute a shell command. */

    printf("About to exec %s\n", args->argv[0]);

    execvp(args->argv[0], args->argv);

    errExit("execvp");
}
#define STACK_SIZE (1024 * 1024)
static char child_stack[STACK_SIZE];    /* Space for child's stack */
int
main(int argc, char *argv[])
{

    int flags, opt, map_zero;

    pid_t child_pid;

    struct child_args args;

    char *uid_map, *gid_map;

    const int MAP_BUF_SIZE = 100;

    char map_buf[MAP_BUF_SIZE];

    char map_path[PATH_MAX];

    /* Parse command-line options. The initial '+' character in

       the final getopt() argument prevents GNU-style permutation

       of command-line options. That's useful, since sometimes

       the 'command' to be executed by this program itself

       has command-line options. We don't want getopt() to treat

       those as options to this program. */

    flags = 0;

    verbose = 0;

    gid_map = NULL;

    uid_map = NULL;

    map_zero = 0;

    while ((opt = getopt(argc, argv, "+imnpuUM:G:zv")) != -1) {

        switch (opt) {

        case 'i': flags |= CLONE_NEWIPC;        break;

        case 'm': flags |= CLONE_NEWNS;         break;

        case 'n': flags |= CLONE_NEWNET;        break;

        case 'p': flags |= CLONE_NEWPID;        break;

        case 'u': flags |= CLONE_NEWUTS;        break;

        case 'v': verbose = 1;                  break;

        case 'z': map_zero = 1;                 break;

        case 'M': uid_map = optarg;             break;

        case 'G': gid_map = optarg;             break;

        case 'U': flags |= CLONE_NEWUSER;       break;

        default:  usage(argv[0]);

        }

    }

    /* -M or -G without -U is nonsensical */

    if (((uid_map != NULL || gid_map != NULL || map_zero) &&

                !(flags & CLONE_NEWUSER)) ||

            (map_zero && (uid_map != NULL || gid_map != NULL)))

        usage(argv[0]);

    args.argv = &argv[optind];

    /* We use a pipe to synchronize the parent and child, in order to

       ensure that the parent sets the UID and GID maps before the child

       calls execve(). This ensures that the child maintains its

       capabilities during the execve() in the common case where we

       want to map the child's effective user ID to 0 in the new user

       namespace. Without this synchronization, the child would lose

       its capabilities if it performed an execve() with nonzero

       user IDs (see the capabilities(7) man page for details of the

       transformation of a process's capabilities during execve()). */

    if (pipe(args.pipe_fd) == -1)

        errExit("pipe");

    /* Create the child in new namespace(s). */

    child_pid = clone(childFunc, child_stack + STACK_SIZE,

                      flags | SIGCHLD, &args);

    if (child_pid == -1)

        errExit("clone");

    /* Parent falls through to here. */

    if (verbose)

        printf("%s: PID of child created by clone() is %jd\n",

                argv[0], (intmax_t) child_pid);

    /* Update the UID and GID maps in the child. */

    if (uid_map != NULL || map_zero) {

        snprintf(map_path, PATH_MAX, "/proc/%jd/uid_map",

                (intmax_t) child_pid);

        if (map_zero) {

            snprintf(map_buf, MAP_BUF_SIZE, "0 %jd 1",

                    (intmax_t) getuid());

            uid_map = map_buf;

        }

        update_map(uid_map, map_path);

    }

    if (gid_map != NULL || map_zero) {

        proc_setgroups_write(child_pid, "deny");

        snprintf(map_path, PATH_MAX, "/proc/%jd/gid_map",

                (intmax_t) child_pid);

        if (map_zero) {

            snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1",

                    (intmax_t) getgid());

            gid_map = map_buf;

        }

        update_map(gid_map, map_path);

    }

    /* Close the write end of the pipe, to signal to the child that we

       have updated the UID and GID maps. */

    close(args.pipe_fd[1]);

    if (waitpid(child_pid, NULL, 0) == -1)      /* Wait for child */

        errExit("waitpid");

    if (verbose)

        printf("%s: terminating\n", argv[0]);

    exit(EXIT_SUCCESS);
}
```

## SEE ALSO
newgidmap(1), newuidmap(1), clone(2), ptrace(2), setns(2), unshare(2), proc(5), subgid(5), subuid(5), capabilities(7), cgroup_namespaces(7), credentials(7), namespaces(7), pid_namespaces(7)

The kernel source file Documentation/namespaces/resource-control.txt.


package: man-pages

title: utf-8(7)

text:
# utf-8(7)

## NAME
UTF-8 - an ASCII compatible multibyte Unicode encoding

## DESCRIPTION
The Unicode 3.0 character set occupies a 16-bit code space. The most obvious Unicode encoding (known as UCS-2) consists of a sequence of 16-bit words. Such strings can contain—as part of many 16-bit characters—bytes such as '\0' or '/', which have a special meaning in filenames and other C library function arguments. In addition, the majority of UNIX tools expect ASCII files and can't read 16-bit words as characters without major modifications. For these reasons, UCS-2 is not a suitable external encoding of Unicode in filenames, text files, environment variables, and so on. The ISO 10646 Universal Character Set (UCS), a superset of Unicode, occupies an even larger code space—31 bits—and the obvious UCS-4 encoding for it (a sequence of 32-bit words) has the same problems.

The UTF-8 encoding of Unicode and UCS does not have these problems and is the common way in which Unicode is used on UNIX-style operating systems.

### Properties
The UTF-8 encoding has the following nice properties:

*

UCS characters 0x00000000 to 0x0000007f (the classic US-ASCII characters) are encoded simply as bytes 0x00 to 0x7f (ASCII compatibility). This means that files and strings which contain only 7-bit ASCII characters have the same encoding under both ASCII and UTF-8 .

*

All UCS characters greater than 0x7f are encoded as a multibyte sequence consisting only of bytes in the range 0x80 to 0xfd, so no ASCII byte can appear as part of another character and there are no problems with, for example, '\0' or '/'.

*

The lexicographic sorting order of UCS-4 strings is preserved.

*

All possible 2^31 UCS codes can be encoded using UTF-8.

*

The bytes 0xc0, 0xc1, 0xfe, and 0xff are never used in the UTF-8 encoding.

*

The first byte of a multibyte sequence which represents a single non-ASCII UCS character is always in the range 0xc2 to 0xfd and indicates how long this multibyte sequence is. All further bytes in a multibyte sequence are in the range 0x80 to 0xbf. This allows easy resynchronization and makes the encoding stateless and robust against missing bytes.

*

UTF-8 encoded UCS characters may be up to six bytes long, however the Unicode standard specifies no characters above 0x10ffff, so Unicode characters can be only up to four bytes long in UTF-8.

### Encoding
The following byte sequences are used to represent a character. The sequence to be used depends on the UCS code number of the character:

0x00000000 - 0x0000007F:

0xxxxxxx

0x00000080 - 0x000007FF:

110xxxxx 10xxxxxx

0x00000800 - 0x0000FFFF:

1110xxxx 10xxxxxx 10xxxxxx

0x00010000 - 0x001FFFFF:

11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

0x00200000 - 0x03FFFFFF:

111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx

0x04000000 - 0x7FFFFFFF:

1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx

The xxx bit positions are filled with the bits of the character code number in binary representation, most significant bit first (big-endian). Only the shortest possible multibyte sequence which can represent the code number of the character can be used.

The UCS code values 0xd800–0xdfff (UTF-16 surrogates) as well as 0xfffe and 0xffff (UCS noncharacters) should not appear in conforming UTF-8 streams. According to RFC 3629 no point above U+10FFFF should be used, which limits characters to four bytes.

### Example
The Unicode character 0xa9 = 1010 1001 (the copyright sign) is encoded in UTF-8 as

11000010 10101001 = 0xc2 0xa9

and character 0x2260 = 0010 0010 0110 0000 (the "not equal" symbol) is encoded as:

11100010 10001001 10100000 = 0xe2 0x89 0xa0

### Application notes
Users have to select a UTF-8 locale, for example with

export LANG=en_GB.UTF-8

in order to activate the UTF-8 support in applications.

Application software that has to be aware of the used character encoding should always set the locale with for example

setlocale(LC_CTYPE, "")

and programmers can then test the expression

strcmp(nl_langinfo(CODESET), "UTF-8") == 0

to determine whether a UTF-8 locale has been selected and whether therefore all plaintext standard input and output, terminal communication, plaintext file content, filenames, and environment variables are encoded in UTF-8.

Programmers accustomed to single-byte encodings such as US-ASCII or ISO 8859 have to be aware that two assumptions made so far are no longer valid in UTF-8 locales. Firstly, a single byte does not necessarily correspond any more to a single character. Secondly, since modern terminal emulators in UTF-8 mode also support Chinese, Japanese, and Korean double-width characters as well as nonspacing combining characters, outputting a single character does not necessarily advance the cursor by one position as it did in ASCII. Library functions such as mbsrtowcs(3) and wcswidth(3) should be used today to count characters and cursor positions.

The official ESC sequence to switch from an ISO 2022 encoding scheme (as used for instance by VT100 terminals) to UTF-8 is ESC % G ("\x1b%G"). The corresponding return sequence from UTF-8 to ISO 2022 is ESC % @ ("\x1b%@"). Other ISO 2022 sequences (such as for switching the G0 and G1 sets) are not applicable in UTF-8 mode.

### Security
The Unicode and UCS standards require that producers of UTF-8 shall use the shortest form possible, for example, producing a two-byte sequence with first byte 0xc0 is nonconforming. Unicode 3.1 has added the requirement that conforming programs must not accept non-shortest forms in their input. This is for security reasons: if user input is checked for possible security violations, a program might check only for the ASCII version of "/../" or ";" or NUL and overlook that there are many non-ASCII ways to represent these things in a non-shortest UTF-8 encoding.

### Standards
ISO/IEC 10646-1:2000, Unicode 3.1, RFC 3629, Plan 9.

## SEE ALSO
locale(1), nl_langinfo(3), setlocale(3), charsets(7), unicode(7)


title: uts_namespaces(7)

summary: overview of Linux UTS namespaces

text:
# uts_namespaces(7)

## NAME
uts_namespaces - overview of Linux UTS namespaces

## DESCRIPTION
UTS namespaces provide isolation of two system identifiers: the hostname and the NIS domain name. These identifiers are set using sethostname(2) and setdomainname(2), and can be retrieved using uname(2), gethostname(2), and getdomainname(2). Changes made to these identifiers are visible to all other processes in the same UTS namespace, but are not visible to processes in other UTS namespaces.

When a process creates a new UTS namespace using clone(2) or unshare(2) with the CLONE_NEWUTS flag, the hostname and domain of the new UTS namespace are copied from the corresponding values in the caller's UTS namespace.

Use of UTS namespaces requires a kernel that is configured with the CONFIG_UTS_NS option.

## SEE ALSO
nsenter(1), unshare(1), clone(2), getdomainname(2), gethostname(2), setns(2), uname(2), unshare(2), namespaces(7)


vdso

title: vdso(7)

text:
# vdso(7)

## NAME
vdso - overview of the virtual ELF dynamic shared object

## SYNOPSIS

```
#include <sys/auxv.h>
```

```
void *vdso = (uintptr_t) getauxval(AT_SYSINFO_EHDR);
```

## DESCRIPTION
The "vDSO" (virtual dynamic shared object) is a small shared library that the kernel automatically maps into the address space of all user-space applications. Applications usually do not need to concern themselves with these details as the vDSO is most commonly called by the C library. This way you can code in the normal way using standard functions and the C library will take care of using any functionality that is available via the vDSO.

Why does the vDSO exist at all? There are some system calls the kernel provides that user-space code ends up using frequently, to the point that such calls can dominate overall performance. This is due both to the frequency of the call as well as the context-switch overhead that results from exiting user space and entering the kernel.

The rest of this documentation is geared toward the curious and/or C library writers rather than general developers. If you're trying to call the vDSO in your own application rather than using the C library, you're most likely doing it wrong.

### Example background
Making system calls can be slow. In x86 32-bit systems, you can trigger a software interrupt (int $0x80) to tell the kernel you wish to make a system call. However, this instruction is expensive: it goes through the full interrupt-handling paths in the processor's microcode as well as in the kernel. Newer processors have faster (but backward incompatible) instructions to initiate system calls. Rather than require the C library to figure out if this functionality is available at run time, the C library can use functions provided by the kernel in the vDSO.

Note that the terminology can be confusing. On x86 systems, the vDSO function used to determine the preferred method of making a system call is named "__kernel_vsyscall", but on x86-64, the term "vsyscall" also refers to an obsolete way to ask the kernel what time it is or what CPU the caller is on.

One frequently used system call is gettimeofday(2). This system call is called both directly by user-space applications as well as indirectly by the C library. Think timestamps or timing loops or polling—all of these frequently need to know what time it is right now. This information is also not secret—any application in any privilege mode (root or any unprivileged user) will get the same answer. Thus the kernel arranges for the information required to answer this question to be placed in memory the process can access. Now a call to gettimeofday(2) changes from a system call to a normal function call and a few memory accesses.

### Finding the vDSO
The base address of the vDSO (if one exists) is passed by the kernel to each program in the initial auxiliary vector (see getauxval(3)), via the AT_SYSINFO_EHDR tag.

You must not assume the vDSO is mapped at any particular location in the user's memory map. The base address will usually be randomized at run time every time a new process image is created (at execve(2) time). This is done for security reasons, to prevent "return-to-libc" attacks.

For some architectures, there is also an AT_SYSINFO tag. This is used only for locating the vsyscall entry point and is frequently omitted or set to 0 (meaning it's not available). This tag is a throwback to the initial vDSO work (see History below) and its use should be avoided.

### File format
Since the vDSO is a fully formed ELF image, you can do symbol lookups on it. This allows new symbols to be added with newer kernel releases, and allows the C library to detect available functionality at run time when running under different kernel versions. Oftentimes the C library will do detection with the first call and then cache the result for subsequent calls.

All symbols are also versioned (using the GNU version format). This allows the kernel to update the function signature without breaking backward compatibility. This means changing the arguments that the function accepts as well as the return value. Thus, when looking up a symbol in the vDSO, you must always include the version to match the ABI you expect.

Typically the vDSO follows the naming convention of prefixing all symbols with "__vdso_" or "__kernel_" so as to distinguish them from other standard symbols. For example, the "gettimeofday" function is named "__vdso_gettimeofday".

You use the standard C calling conventions when calling any of these functions. No need to worry about weird register or stack behavior.

## NOTES

### Source
When you compile the kernel, it will automatically compile and link the vDSO code for you. You will frequently find it under the architecture-specific directory:

find arch/$ARCH/ -name '*vdso*.so*' -o -name '*gate*.so*'

### vDSO names
The name of the vDSO varies across architectures. It will often show up in things like glibc's ldd(1) output. The exact name should not matter to any code, so do not hardcode it.

user ABI

vDSO name

aarch64

linux-vdso.so.1

arm

linux-vdso.so.1

ia64

linux-gate.so.1

mips

linux-vdso.so.1

ppc/32

linux-vdso32.so.1

ppc/64

linux-vdso64.so.1

riscv

linux-vdso.so.1

s390

linux-vdso32.so.1

s390x

linux-vdso64.so.1

sh

linux-gate.so.1

i386

linux-gate.so.1

x86-64

linux-vdso.so.1

x86/x32

linux-vdso.so.1

### strace(1), seccomp(2), and the vDSO
When tracing systems calls with strace(1), symbols (system calls) that are exported by the vDSO will not appear in the trace output. Those system calls will likewise not be visible to seccomp(2) filters.

## ARCHITECTURE-SPECIFIC NOTES
The subsections below provide architecture-specific notes on the vDSO.

Note that the vDSO that is used is based on the ABI of your user-space code and not the ABI of the kernel. Thus, for example, when you run an i386 32-bit ELF binary, you'll get the same vDSO regardless of whether you run it under an i386 32-bit kernel or under an x86-64 64-bit kernel. Therefore, the name of the user-space ABI should be used to determine which of the sections below is relevant.

### ARM functions
The table below lists the symbols exported by the vDSO.

symbol

version

__vdso_gettimeofday

LINUX_2.6 (exported since Linux 4.1)

__vdso_clock_gettime

LINUX_2.6 (exported since Linux 4.1)

Additionally, the ARM port has a code page full of utility functions. Since it's just a raw page of code, there is no ELF information for doing symbol lookups or versioning. It does provide support for different versions though.

For information on this code page, it's best to refer to the kernel documentation as it's extremely detailed and covers everything you need to know: Documentation/arm/kernel_user_helpers.txt.

### aarch64 functions
The table below lists the symbols exported by the vDSO.

symbol

version

__kernel_rt_sigreturn

LINUX_2.6.39

__kernel_gettimeofday

LINUX_2.6.39

__kernel_clock_gettime

LINUX_2.6.39

__kernel_clock_getres

LINUX_2.6.39

### bfin (Blackfin) functions (port removed in Linux 4.17)
As this CPU lacks a memory management unit (MMU), it doesn't set up a vDSO in the normal sense. Instead, it maps at boot time a few raw functions into a fixed location in memory. User-space applications then call directly into that region. There is no provision for backward compatibility beyond sniffing raw opcodes, but as this is an embedded CPU, it can get away with things—some of the object formats it runs aren't even ELF based (they're bFLT/FLAT).

For information on this code page, it's best to refer to the public documentation:

http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:fixed-code

### mips functions
The table below lists the symbols exported by the vDSO.

symbol

version

__kernel_gettimeofday

LINUX_2.6 (exported since Linux 4.4)

__kernel_clock_gettime

LINUX_2.6 (exported since Linux 4.4)

### ia64 (Itanium) functions
The table below lists the symbols exported by the vDSO.

symbol

version

__kernel_sigtramp

LINUX_2.5

__kernel_syscall_via_break

LINUX_2.5

__kernel_syscall_via_epc

LINUX_2.5

The Itanium port is somewhat tricky. In addition to the vDSO above, it also has "light-weight system calls" (also known as "fast syscalls" or "fsys"). You can invoke these via the __kernel_syscall_via_epc vDSO helper. The system calls listed here have the same semantics as if you called them directly via syscall(2), so refer to the relevant documentation for each. The table below lists the functions available via this mechanism.

function

clock_gettime

getcpu

getpid

getppid

gettimeofday

set_tid_address

### parisc (hppa) functions
The parisc port has a code page with utility functions called a gateway page. Rather than use the normal ELF auxiliary vector approach, it passes the address of the page to the process via the SR2 register. The permissions on the page are such that merely executing those addresses automatically executes with kernel privileges and not in user space. This is done to match the way HP-UX works.

Since it's just a raw page of code, there is no ELF information for doing symbol lookups or versioning. Simply call into the appropriate offset via the branch instruction, for example:

ble <offset>(%sr2, %r0)

offset

function

00b0

lws_entry (CAS operations)

00e0

set_thread_pointer (used by glibc)

0100

linux_gateway_entry (syscall)

### ppc/32 functions
The table below lists the symbols exported by the vDSO. The functions marked with a * are available only when the kernel is a PowerPC64 (64-bit) kernel.

symbol

version

__kernel_clock_getres

LINUX_2.6.15

__kernel_clock_gettime

LINUX_2.6.15

__kernel_datapage_offset

LINUX_2.6.15

__kernel_get_syscall_map

LINUX_2.6.15

__kernel_get_tbfreq

LINUX_2.6.15

__kernel_getcpu *

LINUX_2.6.15

__kernel_gettimeofday

LINUX_2.6.15

__kernel_sigtramp_rt32

LINUX_2.6.15

__kernel_sigtramp32

LINUX_2.6.15

__kernel_sync_dicache

LINUX_2.6.15

__kernel_sync_dicache_p5

LINUX_2.6.15

The CLOCK_REALTIME_COARSE and CLOCK_MONOTONIC_COARSE clocks are not supported by the __kernel_clock_getres and __kernel_clock_gettime interfaces; the kernel falls back to the real system call.

### ppc/64 functions
The table below lists the symbols exported by the vDSO.

symbol

version

__kernel_clock_getres

LINUX_2.6.15

__kernel_clock_gettime

LINUX_2.6.15

__kernel_datapage_offset

LINUX_2.6.15

__kernel_get_syscall_map

LINUX_2.6.15

__kernel_get_tbfreq

LINUX_2.6.15

__kernel_getcpu

LINUX_2.6.15

__kernel_gettimeofday

LINUX_2.6.15

__kernel_sigtramp_rt64

LINUX_2.6.15

__kernel_sync_dicache

LINUX_2.6.15

__kernel_sync_dicache_p5

LINUX_2.6.15

The CLOCK_REALTIME_COARSE and CLOCK_MONOTONIC_COARSE clocks are not supported by the __kernel_clock_getres and __kernel_clock_gettime interfaces; the kernel falls back to the real system call.

### riscv functions
The table below lists the symbols exported by the vDSO.

symbol

version

__kernel_rt_sigreturn

LINUX_4.15

__kernel_gettimeofday

LINUX_4.15

__kernel_clock_gettime

LINUX_4.15

__kernel_clock_getres

LINUX_4.15

__kernel_getcpu

LINUX_4.15

__kernel_flush_icache

LINUX_4.15

### s390 functions
The table below lists the symbols exported by the vDSO.

symbol

version

__kernel_clock_getres

LINUX_2.6.29

__kernel_clock_gettime

LINUX_2.6.29

__kernel_gettimeofday

LINUX_2.6.29

### s390x functions
The table below lists the symbols exported by the vDSO.

symbol

version

__kernel_clock_getres

LINUX_2.6.29

__kernel_clock_gettime

LINUX_2.6.29

__kernel_gettimeofday

LINUX_2.6.29

### sh (SuperH) functions
The table below lists the symbols exported by the vDSO.

symbol

version

__kernel_rt_sigreturn

LINUX_2.6

__kernel_sigreturn

LINUX_2.6

__kernel_vsyscall

LINUX_2.6

### i386 functions
The table below lists the symbols exported by the vDSO.

symbol

version

__kernel_sigreturn

LINUX_2.5

__kernel_rt_sigreturn

LINUX_2.5

__kernel_vsyscall

LINUX_2.5

__vdso_clock_gettime

LINUX_2.6 (exported since Linux 3.15)

__vdso_gettimeofday

LINUX_2.6 (exported since Linux 3.15)

__vdso_time

LINUX_2.6 (exported since Linux 3.15)

### x86-64 functions
The table below lists the symbols exported by the vDSO. All of these symbols are also available without the "__vdso_" prefix, but you should ignore those and stick to the names below.

symbol

version

__vdso_clock_gettime

LINUX_2.6

__vdso_getcpu

LINUX_2.6

__vdso_gettimeofday

LINUX_2.6

__vdso_time

LINUX_2.6

### x86/x32 functions
The table below lists the symbols exported by the vDSO.

symbol

version

__vdso_clock_gettime

LINUX_2.6

__vdso_getcpu

LINUX_2.6

__vdso_gettimeofday

LINUX_2.6

__vdso_time

LINUX_2.6

### History
The vDSO was originally just a single function—the vsyscall. In older kernels, you might see that name in a process's memory map rather than "vdso". Over time, people realized that this mechanism was a great way to pass more functionality to user space, so it was reconceived as a vDSO in the current format.

## SEE ALSO
syscalls(2), getauxval(3), proc(5)

The documents, examples, and source code in the Linux source code tree:

```
Documentation/ABI/stable/vdso
Documentation/ia64/fsys.txt
Documentation/vDSO/* (includes examples of using the vDSO)
find arch/ -iname '*vdso*' -o -iname '*gate*'
```


vsock

title: vsock(7)

summary: Linux VSOCK address family

text:
# vsock(7)

## NAME
vsock - Linux VSOCK address family

## SYNOPSIS

```
#include <sys/socket.h>
#include <linux/vm_sockets.h>
```

```
stream_socket = socket(AF_VSOCK, SOCK_STREAM, 0);
datagram_socket = socket(AF_VSOCK, SOCK_DGRAM, 0);
```

## DESCRIPTION
The VSOCK address family facilitates communication between virtual machines and the host they are running on. This address family is used by guest agents and hypervisor services that need a communications channel that is independent of virtual machine network configuration.

Valid socket types are SOCK_STREAM and SOCK_DGRAM. SOCK_STREAM provides connection-oriented byte streams with guaranteed, in-order delivery. SOCK_DGRAM provides a connectionless datagram packet service with best-effort delivery and best-effort ordering. Availability of these socket types is dependent on the underlying hypervisor.

A new socket is created with

```
socket(AF_VSOCK, socket_type, 0);
```

When a process wants to establish a connection, it calls connect(2) with a given destination socket address. The socket is automatically bound to a free port if unbound.

A process can listen for incoming connections by first binding to a socket address using bind(2) and then calling listen(2).

Data is transmitted using the send(2) or write(2) families of system calls and data is received using the recv(2) or read(2) families of system calls.

### Address format
A socket address is defined as a combination of a 32-bit Context Identifier (CID) and a 32-bit port number. The CID identifies the source or destination, which is either a virtual machine or the host. The port number differentiates between multiple services running on a single machine.

```
struct sockaddr_vm {

    sa_family_t    svm_family;    /* Address family: AF_VSOCK */

    unsigned short svm_reserved1;

    unsigned int   svm_port;      /* Port # in host byte order */

    unsigned int   svm_cid;       /* Address in host byte order */

    unsigned char  svm_zero[sizeof(struct sockaddr) -

                            sizeof(sa_family_t) -

                            sizeof(unsigned short) -

                            sizeof(unsigned int) -

                            sizeof(unsigned int)];
};
```

svm_family is always set to AF_VSOCK. svm_reserved1 is always set to 0. svm_port contains the port number in host byte order. The port numbers below 1024 are called privileged ports. Only a process with the CAP_NET_BIND_SERVICE capability may bind(2) to these port numbers. svm_zero must be zero-filled.

There are several special addresses: VMADDR_CID_ANY (-1U) means any address for binding; VMADDR_CID_HYPERVISOR (0) is reserved for services built into the hypervisor; VMADDR_CID_LOCAL (1) is the well-known address for local communication (loopback); VMADDR_CID_HOST (2) is the well-known address of the host.

The special constant VMADDR_PORT_ANY (-1U) means any port number for binding.

### Live migration
Sockets are affected by live migration of virtual machines. Connected SOCK_STREAM sockets become disconnected when the virtual machine migrates to a new host. Applications must reconnect when this happens.

The local CID may change across live migration if the old CID is not available on the new host. Bound sockets are automatically updated to the new CID.

### Ioctls
The following ioctls are available on the /dev/vsock device.

IOCTL_VM_SOCKETS_GET_LOCAL_CID

Get the CID of the local machine. The argument is a pointer to an unsigned int.

```
ioctl(fd, IOCTL_VM_SOCKETS_GET_LOCAL_CID, &cid);

```

Consider using VMADDR_CID_ANY when binding instead of getting the local CID with IOCTL_VM_SOCKETS_GET_LOCAL_CID.

### Local communication
VMADDR_CID_LOCAL (1) directs packets to the same host that generated them. This is useful for testing applications on a single host and for debugging.

The local CID obtained with IOCTL_VM_SOCKETS_GET_LOCAL_CID can be used for the same purpose, but it is preferable to use VMADDR_CID_LOCAL .

## ERRORS
EACCES

Unable to bind to a privileged port without the CAP_NET_BIND_SERVICE capability.

EADDRINUSE

Unable to bind to a port that is already in use.

EADDRNOTAVAIL

Unable to find a free port for binding or unable to bind to a nonlocal CID.

EINVAL

Invalid parameters. This includes: attempting to bind a socket that is already bound, providing an invalid struct sockaddr_vm, and other input validation errors.

ENOPROTOOPT

Invalid socket option in setsockopt(2) or getsockopt(2).

ENOTCONN

Unable to perform operation on an unconnected socket.

EOPNOTSUPP

Operation not supported. This includes: the MSG_OOB flag that is not implemented for the send(2) family of syscalls and MSG_PEEK for the recv(2) family of syscalls.

EPROTONOSUPPORT

Invalid socket protocol number. The protocol should always be 0.

ESOCKTNOSUPPORT

Unsupported socket type in socket(2). Only SOCK_STREAM and SOCK_DGRAM are valid.

## VERSIONS
Support for VMware (VMCI) has been available since Linux 3.9. KVM (virtio) is supported since Linux 4.8. Hyper-V is supported since Linux 4.14.

VMADDR_CID_LOCAL is supported since Linux 5.6. Local communication in the guest and on the host is available since Linux 5.6. Previous versions supported only local communication within a guest (not on the host), and with only some transports (VMCI and virtio).

## SEE ALSO
bind(2), connect(2), listen(2), recv(2), send(2), socket(2), capabilities(7)


title: x25(7)

text:
# x25(7)

## NAME
x25 - ITU-T X.25 / ISO-8208 protocol interface

## SYNOPSIS

```
#include <sys/socket.h>
#include <linux/x25.h>
```

```
x25_socket = socket(AF_X25, SOCK_SEQPACKET, 0);
```

## DESCRIPTION
X25 sockets provide an interface to the X.25 packet layer protocol. This allows applications to communicate over a public X.25 data network as standardized by International Telecommunication Union's recommendation X.25 (X.25 DTE-DCE mode). X25 sockets can also be used for communication without an intermediate X.25 network (X.25 DTE-DTE mode) as described in ISO-8208.

Message boundaries are preserved — a read(2) from a socket will retrieve the same chunk of data as output with the corresponding write(2) to the peer socket. When necessary, the kernel takes care of segmenting and reassembling long messages by means of the X.25 M-bit. There is no hard-coded upper limit for the message size. However, reassembling of a long message might fail if there is a temporary lack of system resources or when other constraints (such as socket memory or buffer size limits) become effective. If that occurs, the X.25 connection will be reset.

### Socket addresses
The AF_X25 socket address family uses the struct sockaddr_x25 for representing network addresses as defined in ITU-T recommendation X.121.

```
struct sockaddr_x25 {

    sa_family_t sx25_family;    /* must be AF_X25 */

    x25_address sx25_addr;      /* X.121 Address */
};
```

sx25_addr contains a char array x25_addr[] to be interpreted as a null-terminated string. sx25_addr.x25_addr[] consists of up to 15 (not counting the terminating null byte) ASCII characters forming the X.121 address. Only the decimal digit characters from '0' to '9' are allowed.

### Socket options
The following X.25-specific socket options can be set by using setsockopt(2) and read with getsockopt(2) with the level argument set to SOL_X25.

X25_QBITINCL

Controls whether the X.25 Q-bit (Qualified Data Bit) is accessible by the user. It expects an integer argument. If set to 0 (default), the Q-bit is never set for outgoing packets and the Q-bit of incoming packets is ignored. If set to 1, an additional first byte is prepended to each message read from or written to the socket. For data read from the socket, a 0 first byte indicates that the Q-bits of the corresponding incoming data packets were not set. A first byte with value 1 indicates that the Q-bit of the corresponding incoming data packets was set. If the first byte of the data written to the socket is 1, the Q-bit of the corresponding outgoing data packets will be set. If the first byte is 0, the Q-bit will not be set.

## VERSIONS
The AF_X25 protocol family is a new feature of Linux 2.2.

## BUGS
Plenty, as the X.25 PLP implementation is CONFIG_EXPERIMENTAL.

This man page is incomplete.

There is no dedicated application programmer's header file yet; you need to include the kernel header file <linux/x25.h>. CONFIG_EXPERIMENTAL might also imply that future versions of the interface are not binary compatible.

X.25 N-Reset events are not propagated to the user process yet. Thus, if a reset occurred, data might be lost without notice.

## SEE ALSO
socket(2), socket(7)

Jonathan Simon Naylor: “The Re-Analysis and Re-Implementation of X.25.” The URL is ftp://ftp.pspt.fi/pub/ham/linux/ax25/x25doc.tgz.


xattr

title: xattr(7)

summary: Extended attributes

text:
# xattr(7)

## NAME
xattr - Extended attributes

## DESCRIPTION
Extended attributes are name:value pairs associated permanently with files and directories, similar to the environment strings associated with a process. An attribute may be defined or undefined. If it is defined, its value may be empty or non-empty.

Extended attributes are extensions to the normal attributes which are associated with all inodes in the system (i.e., the stat(2) data). They are often used to provide additional functionality to a filesystem—for example, additional security features such as Access Control Lists (ACLs) may be implemented using extended attributes.

Users with search access to a file or directory may use listxattr(2) to retrieve a list of attribute names defined for that file or directory.

Extended attributes are accessed as atomic objects. Reading (getxattr(2)) retrieves the whole value of an attribute and stores it in a buffer. Writing (setxattr(2)) replaces any previous value with the new value.

Space consumed for extended attributes may be counted towards the disk quotas of the file owner and file group.

### Extended attribute namespaces
Attribute names are null-terminated strings. The attribute name is always specified in the fully qualified namespace.attribute form, for example, user.mime_type, trusted.md5sum, system.posix_acl_access, or security.selinux.

The namespace mechanism is used to define different classes of extended attributes. These different classes exist for several reasons; for example, the permissions and capabilities required for manipulating extended attributes of one namespace may differ to another.

Currently, the security, system, trusted, and user extended attribute classes are defined as described below. Additional classes may be added in the future.

### Extended security attributes
The security attribute namespace is used by kernel security modules, such as Security Enhanced Linux, and also to implement file capabilities (see capabilities(7)). Read and write access permissions to security attributes depend on the policy implemented for each security attribute by the security module. When no security module is loaded, all processes have read access to extended security attributes, and write access is limited to processes that have the CAP_SYS_ADMIN capability.

### System extended attributes
System extended attributes are used by the kernel to store system objects such as Access Control Lists. Read and write access permissions to system attributes depend on the policy implemented for each system attribute implemented by filesystems in the kernel.

### Trusted extended attributes
Trusted extended attributes are visible and accessible only to processes that have the CAP_SYS_ADMIN capability. Attributes in this class are used to implement mechanisms in user space (i.e., outside the kernel) which keep information in extended attributes to which ordinary processes should not have access.

### User extended attributes
User extended attributes may be assigned to files and directories for storing arbitrary additional information such as the mime type, character set or encoding of a file. The access permissions for user attributes are defined by the file permission bits: read permission is required to retrieve the attribute value, and writer permission is required to change it.

The file permission bits of regular files and directories are interpreted differently from the file permission bits of special files and symbolic links. For regular files and directories the file permission bits define access to the file's contents, while for device special files they define access to the device described by the special file. The file permissions of symbolic links are not used in access checks. These differences would allow users to consume filesystem resources in a way not controllable by disk quotas for group or world writable special files and directories.

For this reason, user extended attributes are allowed only for regular files and directories, and access to user extended attributes is restricted to the owner and to users with appropriate capabilities for directories with the sticky bit set (see the chmod(1) manual page for an explanation of the sticky bit).

### Filesystem differences
The kernel and the filesystem may place limits on the maximum number and size of extended attributes that can be associated with a file. The VFS imposes limitations that an attribute names is limited to 255 bytes and an attribute value is limited to 64 kB. The list of attribute names that can be returned is also limited to 64 kB (see BUGS in listxattr(2)).

Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), require the filesystem to be mounted with the user_xattr mount option in order for user extended attributes to be used.

In the current ext2, ext3, and ext4 filesystem implementations, the total bytes used by the names and values of all of a file's extended attributes must fit in a single filesystem block (1024, 2048 or 4096 bytes, depending on the block size specified when the filesystem was created).

In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no practical limit on the number of extended attributes associated with a file, and the algorithms used to store extended attribute information on disk are scalable.

In the JFS, XFS, and Reiserfs filesystem implementations, the limit on bytes used in an EA value is the ceiling imposed by the VFS.

In the Btrfs filesystem implementation, the total bytes used for the name, value, and implementation overhead bytes is limited to the filesystem nodesize value (16 kB by default).

## CONFORMING TO
Extended attributes are not specified in POSIX.1, but some other systems (e.g., the BSDs and Solaris) provide a similar feature.

## NOTES
Since the filesystems on which extended attributes are stored might also be used on architectures with a different byte order and machine word size, care should be taken to store attribute values in an architecture-independent format.

This page was formerly named attr(5).

## SEE ALSO
attr(1), getfattr(1), setfattr(1), getxattr(2), ioctl_iflags(2), listxattr(2), removexattr(2), setxattr(2), acl(5), capabilities(7), selinux(8)


aio.h

package: man-pages-posix-devel

title: aio.h(7p)

text:
# aio.h(7p)

## PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

## NAME
aio.h — asynchronous input and output

## SYNOPSIS

```
#include <aio.h>
```

## DESCRIPTION
The <aio.h> header shall define the aiocb structure, which shall include at least the following members:

```
int             aio_fildes     File descriptor.
off_t           aio_offset     File offset.
volatile void  *aio_buf        Location of buffer.
size_t          aio_nbytes     Length of transfer.
int             aio_reqprio    Request priority offset.
struct sigevent aio_sigevent   Signal number and value.
int             aio_lio_opcode Operation to be performed.
```

The <aio.h> header shall define the off_t, pthread_attr_t, size_t, and ssize_t types as described in <sys/types.h>.

The <aio.h> header shall define the struct timespec structure as described in <time.h>.

The <aio.h> header shall define the sigevent structure and sigval union as described in <signal.h>.

The <aio.h> header shall define the following symbolic constants:

AIO_ALLDONE

A return value indicating that none of the requested operations could be canceled since they are already complete.

AIO_CANCELED

A return value indicating that all requested operations have been canceled.

AIO_NOTCANCELED

A return value indicating that some of the requested operations could not be canceled since they are in progress.

LIO_NOP

A lio_listio() element operation option indicating that no transfer is requested.

LIO_NOWAIT

A lio_listio() synchronization operation indicating that the calling thread is to continue execution while the lio_listio() operation is being performed, and no notification is given when the operation is complete.

LIO_READ

A lio_listio() element operation option requesting a read.

LIO_WAIT

A lio_listio() synchronization operation indicating that the calling thread is to suspend until the lio_listio() operation is complete.

LIO_WRITE

A lio_listio() element operation option requesting a write.

The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.

```
int      aio_cancel(int, struct aiocb *);
int      aio_error(const struct aiocb *);
int      aio_fsync(int, struct aiocb *);
int      aio_read(struct aiocb *);
ssize_t  aio_return(struct aiocb *);
int      aio_suspend(const struct aiocb *const [], int,

             const struct timespec *);
int      aio_write(struct aiocb *);
int      lio_listio(int, struct aiocb *restrict const [restrict], int,

             struct sigevent *restrict);
```

Inclusion of the <aio.h> header may make visible symbols defined in the headers <fcntl.h>, <signal.h>, and <time.h>.

The following sections are informative.

## APPLICATION USAGE
None.

## RATIONALE
None.

## FUTURE DIRECTIONS
None.

## SEE ALSO
<fcntl.h>, <signal.h>, <sys_types.h>, <time.h>

The System Interfaces volume of POSIX.1‐2017, aio_cancel(), aio_error(), aio_fsync(), aio_read(), aio_return(), aio_suspend(), aio_write(), fsync(), lio_listio(), lseek(), read(), write()

## COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .


title: arpa_inet.h(7p)

text:
# arpa_inet.h(7p)

## PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

## NAME
arpa/inet.h — definitions for internet operations

## SYNOPSIS

```
#include <arpa/inet.h>
```

## DESCRIPTION
The <arpa/inet.h> header shall define the in_port_t and in_addr_t types as described in <netinet/in.h>.

The <arpa/inet.h> header shall define the in_addr structure as described in <netinet/in.h>.

The <arpa/inet.h> header shall define the INET_ADDRSTRLEN and INET6_ADDRSTRLEN macros as described in <netinet/in.h>.

The following shall be declared as functions, or defined as macros, or both. If functions are declared, function prototypes shall be provided.

```
uint32_t htonl(uint32_t);
uint16_t htons(uint16_t);
uint32_t ntohl(uint32_t);
uint16_t ntohs(uint16_t);
```

The <arpa/inet.h> header shall define the uint32_t and uint16_t types as described in <inttypes.h>.

The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.

```
in_addr_t    inet_addr(const char *);
char        *inet_ntoa(struct in_addr);
const char  *inet_ntop(int, const void *restrict, char *restrict,

                 socklen_t);
int          inet_pton(int, const char *restrict, void *restrict);
```

Inclusion of the <arpa/inet.h> header may also make visible all symbols from <netinet/in.h> and <inttypes.h>.

The following sections are informative.

## APPLICATION USAGE
None.

## RATIONALE
None.

## FUTURE DIRECTIONS
None.

## SEE ALSO
<inttypes.h>, <netinet_in.h>

The System Interfaces volume of POSIX.1‐2017, htonl(), inet_addr(), inet_ntop()

## COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .


assert.h

title: assert.h(7p)

text:
# assert.h(7p)

## PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

## NAME
assert.h — verify program assertion

## SYNOPSIS

```
#include <assert.h>
```

## DESCRIPTION
The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1‐2017 defers to the ISO C standard.

The <assert.h> header shall define the assert() macro. It refers to the macro NDEBUG which is not defined in the header. If NDEBUG is defined as a macro name before the inclusion of this header, the assert() macro shall be defined simply as:

```
#define assert(ignore)((void) 0)
```

Otherwise, the macro behaves as described in assert().

The assert() macro shall be redefined according to the current state of NDEBUG each time <assert.h> is included.

The assert() macro shall be implemented as a macro, not as a function. If the macro definition is suppressed in order to access an actual function, the behavior is undefined.

The following sections are informative.

## APPLICATION USAGE
None.

## RATIONALE
None.

## FUTURE DIRECTIONS
None.

## SEE ALSO
The System Interfaces volume of POSIX.1‐2017, assert()

## COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .


complex.h

title: complex.h(7p)

text:
# complex.h(7p)

## PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

## NAME
complex.h — complex arithmetic

## SYNOPSIS

```
#include <complex.h>
```

## DESCRIPTION
The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1‐2017 defers to the ISO C standard.

The <complex.h> header shall define the following macros:

complex

Expands to _Complex.

_Complex_I

Expands to a constant expression of type const float _Complex, with the value of the imaginary unit (that is, a number i such that i2=-1).

imaginary

Expands to _Imaginary.

_Imaginary_I

Expands to a constant expression of type const float _Imaginary with the value of the imaginary unit.

I

Expands to either _Imaginary_I or _Complex_I. If _Imaginary_I is not defined, I expands to _Complex_I.

The macros imaginary and _Imaginary_I shall be defined if and only if the implementation supports imaginary types.

An application may undefine and then, perhaps, redefine the complex, imaginary, and I macros.

The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.

```
double               cabs(double complex);
float                cabsf(float complex);
long double          cabsl(long double complex);
double complex       cacos(double complex);
float complex        cacosf(float complex);
double complex       cacosh(double complex);
float complex        cacoshf(float complex);
long double complex  cacoshl(long double complex);
long double complex  cacosl(long double complex);
double               carg(double complex);
float                cargf(float complex);
long double          cargl(long double complex);
double complex       casin(double complex);
float complex        casinf(float complex);
double complex       casinh(double complex);
float complex        casinhf(float complex);
long double complex  casinhl(long double complex);
long double complex  casinl(long double complex);
double complex       catan(double complex);
float complex        catanf(float complex);
double complex       catanh(double complex);
float complex        catanhf(float complex);
long double complex  catanhl(long double complex);
long double complex  catanl(long double complex);
double complex       ccos(double complex);
float complex        ccosf(float complex);
double complex       ccosh(double complex);
float complex        ccoshf(float complex);
long double complex  ccoshl(long double complex);
long double complex  ccosl(long double complex);
double complex       cexp(double complex);
float complex        cexpf(float complex);
long double complex  cexpl(long double complex);
double               cimag(double complex);
float                cimagf(float complex);
long double          cimagl(long double complex);
double complex       clog(double complex);
float complex        clogf(float complex);
long double complex  clogl(long double complex);
double complex       conj(double complex);
float complex        conjf(float complex);
long double complex  conjl(long double complex);
double complex       cpow(double complex, double complex);
float complex        cpowf(float complex, float complex);
long double complex  cpowl(long double complex, long double complex);
double complex       cproj(double complex);
float complex        cprojf(float complex);
long double complex  cprojl(long double complex);
double               creal(double complex);
float                crealf(float complex);
long double          creall(long double complex);
double complex       csin(double complex);
float complex        csinf(float complex);
double complex       csinh(double complex);
float complex        csinhf(float complex);
long double complex  csinhl(long double complex);
long double complex  csinl(long double complex);
double complex       csqrt(double complex);
float complex        csqrtf(float complex);
long double complex  csqrtl(long double complex);
double complex       ctan(double complex);
float complex        ctanf(float complex);
double complex       ctanh(double complex);
float complex        ctanhf(float complex);
long double complex  ctanhl(long double complex);
long double complex  ctanl(long double complex);
```

The following sections are informative.

## APPLICATION USAGE
Values are interpreted as radians, not degrees.

## RATIONALE
The choice of I instead of i for the imaginary unit concedes to the widespread use of the identifier i for other purposes. The application can use a different identifier, say j, for the imaginary unit by following the inclusion of the <complex.h> header with:

```
#undef I
#define j _Imaginary_I
```

An I suffix to designate imaginary constants is not required, as multiplication by I provides a sufficiently convenient and more generally useful notation for imaginary terms. The corresponding real type for the imaginary unit is float, so that use of I for algorithmic or notational convenience will not result in widening types.

On systems with imaginary types, the application has the ability to control whether use of the macro I introduces an imaginary type, by explicitly defining I to be _Imaginary_I or _Complex_I. Disallowing imaginary types is useful for some applications intended to run on implementations without support for such types.

The macro _Imaginary_I provides a test for whether imaginary types are supported.

The cis() function (cos(x) + I*sin(x)) was considered but rejected because its implementation is easy and straightforward, even though some implementations could compute sine and cosine more efficiently in tandem.

## FUTURE DIRECTIONS
The following function names and the same names suffixed with f or l are reserved for future use, and may be added to the declarations in the <complex.h> header.

cerf() cerfc() cexp2()

cexpm1() clog10() clog1p()

clog2() clgamma() ctgamma()

## SEE ALSO
The System Interfaces volume of POSIX.1‐2017, cabs(), cacos(), cacosh(), carg(), casin(), casinh(), catan(), catanh(), ccos(), ccosh(), cexp(), cimag(), clog(), conj(), cpow(), cproj(), creal(), csin(), csinh(), csqrt(), ctan(), ctanh()

## COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .


cpio.h

title: cpio.h(7p)

text:
# cpio.h(7p)

## PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

## NAME
cpio.h — cpio archive values

## SYNOPSIS

```
#include <cpio.h>
```

## DESCRIPTION
The <cpio.h> header shall define the symbolic constants needed by the c_mode field of the cpio archive format, with the names and values given in the following table:

Name

Description

Value (Octal)

C_IRUSR

Read by owner.

0000400

C_IWUSR

Write by owner.

0000200

C_IXUSR

Execute by owner.

0000100

C_IRGRP

Read by group.

0000040

C_IWGRP

Write by group.

0000020

C_IXGRP

Execute by group.

0000010

C_IROTH

Read by others.

0000004

C_IWOTH

Write by others.

0000002

C_IXOTH

Execute by others.

0000001

C_ISUID

Set user ID.

0004000

C_ISGID

Set group ID.

0002000

C_ISVTX

On directories, restricted deletion flag.

0001000

C_ISDIR

Directory.

0040000

C_ISFIFO

FIFO.

0010000

C_ISREG

Regular file.

0100000

C_ISBLK

Block special.

0060000

C_ISCHR

Character special.

0020000

C_ISCTG

Reserved.

0110000

C_ISLNK

Symbolic link.

0120000

C_ISSOCK

Socket.

0140000

The <cpio.h> header shall define the following symbolic constant as a string:

```
MAGIC    "070707"
```

The following sections are informative.

## APPLICATION USAGE
None.

## RATIONALE
None.

## FUTURE DIRECTIONS
None.

## SEE ALSO
The Shell and Utilities volume of POSIX.1‐2017, pax

## COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .


ctype.h

title: ctype.h(7p)

text:
# ctype.h(7p)

## PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

## NAME
ctype.h — character types

## SYNOPSIS

```
#include <ctype.h>
```

## DESCRIPTION
Some of the functionality described on this reference page extends the ISO C standard. Applications shall define the appropriate feature test macro (see the System Interfaces volume of POSIX.1‐2017, Section 2.2, The Compilation Environment) to enable the visibility of these symbols in this header.

The <ctype.h> header shall define the locale_t type as described in <locale.h>, representing a locale object.

The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided for use with ISO C standard compilers.

```
int   isalnum(int);
int   isalnum_l(int, locale_t);
int   isalpha(int);
int   isalpha_l(int, locale_t);
int   isascii(int);
int   isblank(int);
int   isblank_l(int, locale_t);
int   iscntrl(int);
int   iscntrl_l(int, locale_t);
int   isdigit(int);
int   isdigit_l(int, locale_t);
int   isgraph(int);
int   isgraph_l(int, locale_t);
int   islower(int);
int   islower_l(int, locale_t);
int   isprint(int);
int   isprint_l(int, locale_t);
int   ispunct(int);
int   ispunct_l(int, locale_t);
int   isspace(int);
int   isspace_l(int, locale_t);
int   isupper(int);
int   isupper_l(int, locale_t);
int   isxdigit(int);
int   isxdigit_l(int, locale_t);
int   toascii(int);
int   tolower(int);
int   tolower_l(int, locale_t);
int   toupper(int);
int   toupper_l(int, locale_t);
```

The <ctype.h> header shall define the following as macros:

```
int   _toupper(int);
int   _tolower(int);
```

The following sections are informative.

## APPLICATION USAGE
None.

## RATIONALE
None.

## FUTURE DIRECTIONS
None.

## SEE ALSO
<locale.h>

The System Interfaces volume of POSIX.1‐2017, Section 2.2, The Compilation Environment, isalnum(), isalpha(), isascii(), isblank(), iscntrl(), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit(), mblen(), mbstowcs(), mbtowc(), setlocale(), toascii(), tolower(), _tolower(), toupper(), _toupper(), wcstombs(), wctomb()

## COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .


dirent.h

title: dirent.h(7p)

text:
# dirent.h(7p)

## PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

## NAME
dirent.h — format of directory entries

## SYNOPSIS

```
#include <dirent.h>
```

## DESCRIPTION
The internal format of directories is unspecified.

The <dirent.h> header shall define the following type:

DIR

A type representing a directory stream. The DIR type may be an incomplete type.

It shall also define the structure dirent which shall include the following members:

```
ino_t  d_ino       File serial number.
char   d_name[]    Filename string of entry.
```

The <dirent.h> header shall define the ino_t type as described in <sys/types.h>.

The array d_name is of unspecified size, but shall contain a filename of at most {NAME_MAX} bytes followed by a terminating null byte.

The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.

```
int            alphasort(const struct dirent **, const struct dirent **);
int            closedir(DIR *);
int            dirfd(DIR *);
DIR           *fdopendir(int);
DIR           *opendir(const char *);
struct dirent *readdir(DIR *);
int            readdir_r(DIR *restrict, struct dirent *restrict,

                   struct dirent **restrict);
void           rewinddir(DIR *);
int            scandir(const char *, struct dirent ***,

                   int (*)(const struct dirent *),

                   int (*)(const struct dirent **,

                   const struct dirent **));
void           seekdir(DIR *, long);
long           telldir(DIR *);
```

The following sections are informative.

## APPLICATION USAGE
None.

## RATIONALE
Information similar to that in the <dirent.h> header is contained in a file <sys/dir.h> in 4.2 BSD and 4.3 BSD. The equivalent in these implementations of struct dirent from this volume of POSIX.1‐2017 is struct direct. The filename was changed because the name <sys/dir.h> was also used in earlier implementations to refer to definitions related to the older access method; this produced name conflicts. The name of the structure was changed because this volume of POSIX.1‐2017 does not completely define what is in the structure, so it could be different on some implementations from struct direct.

The name of an array of char of an unspecified size should not be used as an lvalue. Use of:

```
sizeof(d_name)
```

is incorrect; use:

```
strlen(d_name)
```

instead.

The array of char d_name is not a fixed size. Implementations may need to declare struct dirent with an array size for d_name of 1, but the actual number of bytes provided matches (or only slightly exceeds) the length of the filename string.

## FUTURE DIRECTIONS
None.

## SEE ALSO
<sys_types.h>

The System Interfaces volume of POSIX.1‐2017, alphasort(), closedir(), dirfd(), fdopendir(), readdir(), rewinddir(), seekdir(), telldir()

## COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .