termio

title: termio(7)

summary: System V terminal driver interface

text:
# termio(7)

## NAME
termio - System V terminal driver interface

## DESCRIPTION
termio is the name of the old System V terminal driver interface. This interface defined a termio structure used to store terminal settings, and a range of ioctl(2) operations to get and set terminal attributes.

The termio interface is now obsolete: POSIX.1-1990 standardized a modified version of this interface, under the name termios. The POSIX.1 data structure differs slightly from the System V version, and POSIX.1 defined a suite of functions to replace the various ioctl(2) operations that existed in System V. (This was done because ioctl(2) was unstandardized, and its variadic third argument does not allow argument type checking.)

If you're looking for a page called "termio", then you can probably find most of the information that you seek in either termios(3) or ioctl_tty(2).

## SEE ALSO
reset(1), setterm(1), stty(1), ioctl_tty(2), termios(3), tty(4)


thread-keyring

package: man-pages

title: thread-keyring(7)

summary: per-thread keyring

text:
# thread-keyring(7)

## NAME
thread-keyring - per-thread keyring

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

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

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

Thread keyrings are not inherited across clone(2) and fork(2) and are cleared by execve(2). A thread keyring is destroyed when the thread that refers to it terminates.

Initially, a thread does not have a thread keyring. If a thread doesn't have a thread keyring when it is accessed, then it will be created if it is to be modified; otherwise the operation fails with the error ENOKEY.

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

branch: sisyphus


time

title: time(7)

summary: overview of time and timers

text:
# time(7)

## NAME
time - overview of time and timers

## DESCRIPTION

### Real time and process time
Real time is defined as time measured from some fixed point, either from a standard point in the past (see the description of the Epoch and calendar time below), or from some point (e.g., the start) in the life of a process (elapsed time).

Process time is defined as the amount of CPU time used by a process. This is sometimes divided into user and system components. User CPU time is the time spent executing code in user mode. System CPU time is the time spent by the kernel executing in system mode on behalf of the process (e.g., executing system calls). The time(1) command can be used to determine the amount of CPU time consumed during the execution of a program. A program can determine the amount of CPU time it has consumed using times(2), getrusage(2), or clock(3).

### The hardware clock
Most computers have a (battery-powered) hardware clock which the kernel reads at boot time in order to initialize the software clock. For further details, see rtc(4) and hwclock(8).

### The software clock, HZ, and jiffies
The accuracy of various system calls that set timeouts, (e.g., select(2), sigtimedwait(2)) and measure CPU time (e.g., getrusage(2)) is limited by the resolution of the software clock, a clock maintained by the kernel which measures time in jiffies. The size of a jiffy is determined by the value of the kernel constant HZ.

The value of HZ varies across kernel versions and hardware platforms. On i386 the situation is as follows: on kernels up to and including Linux 2.4.x, HZ was 100, giving a jiffy value of 0.01 seconds; starting with Linux 2.6.0, HZ was raised to 1000, giving a jiffy of 0.001 seconds. Since Linux 2.6.13, the HZ value is a kernel configuration parameter and can be 100, 250 (the default) or 1000, yielding a jiffies value of, respectively, 0.01, 0.004, or 0.001 seconds. Since Linux 2.6.20, a further frequency is available: 300, a number that divides evenly for the common video frame rates (PAL, 25 Hz; NTSC, 30 Hz).

The times(2) system call is a special case. It reports times with a granularity defined by the kernel constant USER_HZ. User-space applications can determine the value of this constant using sysconf(_SC_CLK_TCK).

### System and process clocks; time namespaces
The kernel supports a range of clocks that measure various kinds of elapsed and virtual (i.e., consumed CPU) time. These clocks are described in clock_gettime(2). A few of the clocks are settable using clock_settime(2). The values of certain clocks are virtualized by time namespaces; see time_namespaces(7).

### High-resolution timers
Before Linux 2.6.21, the accuracy of timer and sleep system calls (see below) was also limited by the size of the jiffy.

Since Linux 2.6.21, Linux supports high-resolution timers (HRTs), optionally configurable via CONFIG_HIGH_RES_TIMERS. On a system that supports HRTs, the accuracy of sleep and timer system calls is no longer constrained by the jiffy, but instead can be as accurate as the hardware allows (microsecond accuracy is typical of modern hardware). You can determine whether high-resolution timers are supported by checking the resolution returned by a call to clock_getres(2) or looking at the "resolution" entries in /proc/timer_list.

HRTs are not supported on all hardware architectures. (Support is provided on x86, ARM, and PowerPC, among others.)

### The Epoch
UNIX systems represent time in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).

A program can determine the calendar time via the clock_gettime(2) CLOCK_REALTIME clock, which returns time (in seconds and nanoseconds) that have elapsed since the Epoch; time(2) provides similar information, but only with accuracy to the nearest second. The system time can be changed using clock_settime(2).

### Broken-down time
Certain library functions use a structure of type tm to represent broken-down time, which stores time value separated out into distinct components (year, month, day, hour, minute, second, etc.). This structure is described in tm(3type), which also describes functions that convert between calendar time and broken-down time. Functions for converting between broken-down time and printable string representations of the time are described in ctime(3), strftime(3), and strptime(3).

### Sleeping and setting timers
Various system calls and functions allow a program to sleep (suspend execution) for a specified period of time; see nanosleep(2), clock_nanosleep(2), and sleep(3).

Various system calls allow a process to set a timer that expires at some point in the future, and optionally at repeated intervals; see alarm(2), getitimer(2), timerfd_create(2), and timer_create(2).

### Timer slack
Since Linux 2.6.28, it is possible to control the "timer slack" value for a thread. The timer slack is the length of time by which the kernel may delay the wake-up of certain system calls that block with a timeout. Permitting this delay allows the kernel to coalesce wake-up events, thus possibly reducing the number of system wake-ups and saving power. For more details, see the description of PR_SET_TIMERSLACK in prctl(2).

## SEE ALSO
date(1), time(1), timeout(1), adjtimex(2), alarm(2), clock_gettime(2), clock_nanosleep(2), getitimer(2), getrlimit(2), getrusage(2), gettimeofday(2), nanosleep(2), stat(2), time(2), timer_create(2), timerfd_create(2), times(2), utime(2), adjtime(3), clock(3), clock_getcpuclockid(3), ctime(3), ntp_adjtime(3), ntp_gettime(3), pthread_getcpuclockid(3), sleep(3), strftime(3), strptime(3), timeradd(3), usleep(3), rtc(4), time_namespaces(7), hwclock(8)


title: time_namespaces(7)

summary: overview of Linux time namespaces

text:
# time_namespaces(7)

## NAME
time_namespaces - overview of Linux time namespaces

## DESCRIPTION
Time namespaces virtualize the values of two system clocks:

•

CLOCK_MONOTONIC (and likewise CLOCK_MONOTONIC_COARSE and CLOCK_MONOTONIC_RAW), a nonsettable clock that represents monotonic time since—as described by POSIX—"some unspecified point in the past".

•

CLOCK_BOOTTIME (and likewise CLOCK_BOOTTIME_ALARM), a nonsettable clock that is identical to CLOCK_MONOTONIC, except that it also includes any time that the system is suspended.

Thus, the processes in a time namespace share per-namespace values for these clocks. This affects various APIs that measure against these clocks, including: clock_gettime(2), clock_nanosleep(2), nanosleep(2), timer_settime(2), timerfd_settime(2), and /proc/uptime.

Currently, the only way to create a time namespace is by calling unshare(2) with the CLONE_NEWTIME flag. This call creates a new time namespace but does not place the calling process in the new namespace. Instead, the calling process's subsequently created children are placed in the new namespace. This allows clock offsets (see below) for the new namespace to be set before the first process is placed in the namespace. The /proc/pid/ns/time_for_children symbolic link shows the time namespace in which the children of a process will be created. (A process can use a file descriptor opened on this symbolic link in a call to setns(2) in order to move into the namespace.)

### /proc/pid/timens_offsets
Associated with each time namespace are offsets, expressed with respect to the initial time namespace, that define the values of the monotonic and boot-time clocks in that namespace. These offsets are exposed via the file /proc/pid/timens_offsets. Within this file, the offsets are expressed as lines consisting of three space-delimited fields:

```
<clock-id> <offset-secs> <offset-nanosecs>
```

The clock-id is a string that identifies the clock whose offsets are being shown. This field is either monotonic, for CLOCK_MONOTONIC, or boottime, for CLOCK_BOOTTIME. The remaining fields express the offset (seconds plus nanoseconds) for the clock in this time namespace. These offsets are expressed relative to the clock values in the initial time namespace. The offset-secs value can be negative, subject to restrictions noted below; offset-nanosecs is an unsigned value.

In the initial time namespace, the contents of the timens_offsets file are as follows:

```
$ cat /proc/self/timens_offsets
monotonic           0         0
boottime            0         0
```

In a new time namespace that has had no member processes, the clock offsets can be modified by writing newline-terminated records of the same form to the timens_offsets file. The file can be written to multiple times, but after the first process has been created in or has entered the namespace, write(2)s on this file fail with the error EACCES. In order to write to the timens_offsets file, a process must have the CAP_SYS_TIME capability in the user namespace that owns the time namespace.

Writes to the timens_offsets file can fail with the following errors:

EINVAL

An offset-nanosecs value is greater than 999,999,999.

EINVAL

A clock-id value is not valid.

EPERM

The caller does not have the CAP_SYS_TIME capability.

ERANGE

An offset-secs value is out of range. In particular;

•

offset-secs can't be set to a value which would make the current time on the corresponding clock inside the namespace a negative value; and

•

offset-secs can't be set to a value such that the time on the corresponding clock inside the namespace would exceed half of the value of the kernel constant KTIME_SEC_MAX (this limits the clock value to a maximum of approximately 146 years).

In a new time namespace created by unshare(2), the contents of the timens_offsets file are inherited from the time namespace of the creating process.

## NOTES
Use of time namespaces requires a kernel that is configured with the CONFIG_TIME_NS option.

Note that time namespaces do not virtualize the CLOCK_REALTIME clock. Virtualization of this clock was avoided for reasons of complexity and overhead within the kernel.

For compatibility with the initial implementation, when writing a clock-id to the /proc/pid/timens_offsets file, the numerical values of the IDs can be written instead of the symbolic names show above; i.e., 1 instead of monotonic, and 7 instead of boottime. For readability, the use of the symbolic names over the numbers is preferred.

The motivation for adding time namespaces was to allow the monotonic and boot-time clocks to maintain consistent values during container migration and checkpoint/restore.

## EXAMPLES
The following shell session demonstrates the operation of time namespaces. We begin by displaying the inode number of the time namespace of a shell in the initial time namespace:

```
$ readlink /proc/$$/ns/time
time:[4026531834]
```

Continuing in the initial time namespace, we display the system uptime using uptime(1) and use the clock_times example program shown in clock_getres(2) to display the values of various clocks:

```
$ uptime --pretty
up 21 hours, 17 minutes
$ ./clock_times
CLOCK_REALTIME : 1585989401.971 (18356 days +  8h 36m 41s)
CLOCK_TAI      : 1585989438.972 (18356 days +  8h 37m 18s)
CLOCK_MONOTONIC:      56338.247 (15h 38m 58s)
CLOCK_BOOTTIME :      76633.544 (21h 17m 13s)
```

We then use unshare(1) to create a time namespace and execute a bash(1) shell. From the new shell, we use the built-in echo command to write records to the timens_offsets file adjusting the offset for the CLOCK_MONOTONIC clock forward 2 days and the offset for the CLOCK_BOOTTIME clock forward 7 days:

```
$ PS1="ns2# " sudo unshare -T -- bash --norc
ns2# echo "monotonic $((2*24*60*60)) 0" > /proc/$$/timens_offsets
ns2# echo "boottime  $((7*24*60*60)) 0" > /proc/$$/timens_offsets
```

Above, we started the bash(1) shell with the --norc option so that no start-up scripts were executed. This ensures that no child processes are created from the shell before we have a chance to update the timens_offsets file.

We then use cat(1) to display the contents of the timens_offsets file. The execution of cat(1) creates the first process in the new time namespace, after which further attempts to update the timens_offsets file produce an error.

```
ns2# cat /proc/$$/timens_offsets
monotonic      172800         0
boottime       604800         0
ns2# echo "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets
bash: echo: write error: Permission denied
```

Continuing in the new namespace, we execute uptime(1) and the clock_times example program:

```
ns2# uptime --pretty
up 1 week, 21 hours, 18 minutes
ns2# ./clock_times
CLOCK_REALTIME : 1585989457.056 (18356 days +  8h 37m 37s)
CLOCK_TAI      : 1585989494.057 (18356 days +  8h 38m 14s)
CLOCK_MONOTONIC:     229193.332 (2 days + 15h 39m 53s)
CLOCK_BOOTTIME :     681488.629 (7 days + 21h 18m  8s)
```

From the above output, we can see that the monotonic and boot-time clocks have different values in the new time namespace.

Examining the /proc/pid/ns/time and /proc/pid/ns/time_for_children symbolic links, we see that the shell is a member of the initial time namespace, but its children are created in the new namespace.

```
ns2# readlink /proc/$$/ns/time
time:[4026531834]
ns2# readlink /proc/$$/ns/time_for_children
time:[4026532900]
ns2# readlink /proc/self/ns/time   # Creates a child process
time:[4026532900]
```

Returning to the shell in the initial time namespace, we see that the monotonic and boot-time clocks are unaffected by the timens_offsets changes that were made in the other time namespace:

```
$ uptime --pretty
up 21 hours, 19 minutes
$ ./clock_times
CLOCK_REALTIME : 1585989401.971 (18356 days +  8h 38m 51s)
CLOCK_TAI      : 1585989438.972 (18356 days +  8h 39m 28s)
CLOCK_MONOTONIC:      56338.247 (15h 41m  8s)
CLOCK_BOOTTIME :      76633.544 (21h 19m 23s)
```

## SEE ALSO
nsenter(1), unshare(1), clock_settime(2), setns(2), unshare(2), namespaces(7), time(7)


udp

title: udp(7)

summary: User Datagram Protocol for IPv4

text:
# udp(7)

## NAME
udp - User Datagram Protocol for IPv4

## SYNOPSIS

```
#include <sys/socket.h>
#include <netinet/in.h>
#include <netinet/udp.h>
```

```
udp_socket = socket(AF_INET, SOCK_DGRAM, 0);
```

## DESCRIPTION
This is an implementation of the User Datagram Protocol described in RFC 768. It implements a connectionless, unreliable datagram packet service. Packets may be reordered or duplicated before they arrive. UDP generates and checks checksums to catch transmission errors.

When a UDP socket is created, its local and remote addresses are unspecified. Datagrams can be sent immediately using sendto(2) or sendmsg(2) with a valid destination address as an argument. When connect(2) is called on the socket, the default destination address is set and datagrams can now be sent using send(2) or write(2) without specifying a destination address. It is still possible to send to other destinations by passing an address to sendto(2) or sendmsg(2). In order to receive packets, the socket can be bound to a local address first by using bind(2). Otherwise, the socket layer will automatically assign a free local port out of the range defined by /proc/sys/net/ipv4/ip_local_port_range and bind the socket to INADDR_ANY.

All receive operations return only one packet. When the packet is smaller than the passed buffer, only that much data is returned; when it is bigger, the packet is truncated and the MSG_TRUNC flag is set. MSG_WAITALL is not supported.

IP options may be sent or received using the socket options described in ip(7). They are processed by the kernel only when the appropriate /proc parameter is enabled (but still passed to the user even when it is turned off). See ip(7).

When the MSG_DONTROUTE flag is set on sending, the destination address must refer to a local interface address and the packet is sent only to that interface.

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

### Address format
UDP uses the IPv4 sockaddr_in address format described in ip(7).

### Error handling
All fatal errors will be passed to the user as an error return even when the socket is not connected. This includes asynchronous errors received from the network. You may get an error for an earlier packet that was sent on the same socket. This behavior differs from many other BSD socket implementations which don't pass any errors unless the socket is connected. Linux's behavior is mandated by RFC 1122.

For compatibility with legacy code, in Linux 2.0 and 2.2 it was possible to set the SO_BSDCOMPAT SOL_SOCKET option to receive remote errors only when the socket has been connected (except for EPROTO and EMSGSIZE). Locally generated errors are always passed. Support for this socket option was removed in later kernels; see socket(7) for further information.

When the IP_RECVERR option is enabled, all errors are stored in the socket error queue, and can be received by recvmsg(2) with the MSG_ERRQUEUE flag set.

### /proc interfaces
System-wide UDP parameter settings can be accessed by files in the directory /proc/sys/net/ipv4/.

udp_mem (since Linux 2.6.25)

This is a vector of three integers governing the number of pages allowed for queueing by all UDP sockets.

min

Below this number of pages, UDP is not bothered about its memory appetite. When the amount of memory allocated by UDP exceeds this number, UDP starts to moderate memory usage.

pressure

This value was introduced to follow the format of tcp_mem (see tcp(7)).

max

Number of pages allowed for queueing by all UDP sockets.

Defaults values for these three items are calculated at boot time from the amount of available memory.

udp_rmem_min (integer; default value: PAGE_SIZE; since Linux 2.6.25)

Minimal size, in bytes, of receive buffers used by UDP sockets in moderation. Each UDP socket is able to use the size for receiving data, even if total pages of UDP sockets exceed udp_mem pressure.

udp_wmem_min (integer; default value: PAGE_SIZE; since Linux 2.6.25)

Minimal size, in bytes, of send buffer used by UDP sockets in moderation. Each UDP socket is able to use the size for sending data, even if total pages of UDP sockets exceed udp_mem pressure.

### Socket options
To set or get a UDP socket option, call getsockopt(2) to read or setsockopt(2) to write the option with the option level argument set to IPPROTO_UDP. Unless otherwise noted, optval is a pointer to an int.

Following is a list of UDP-specific socket options. For details of some other socket options that are also applicable for UDP sockets, see socket(7).

UDP_CORK (since Linux 2.5.44)

If this option is enabled, then all data output on this socket is accumulated into a single datagram that is transmitted when the option is disabled. This option should not be used in code intended to be portable.

UDP_SEGMENT (since Linux 4.18)

Enables UDP segmentation offload. Segmentation offload reduces send(2) cost by transferring multiple datagrams worth of data as a single large packet through the kernel transmit path, even when that exceeds MTU. As late as possible, the large packet is split by segment size into a series of datagrams. This segmentation offload step is deferred to hardware if supported, else performed in software. This option takes a value in the range [0, USHRT_MAX] that sets the segment size: the size of datagram payload, excluding the UDP header. The segment size must be chosen such that at most 64 datagrams are sent in a single call and that the datagrams after segmentation meet the same MTU rules that apply to datagrams sent without this option. Segmentation offload depends on checksum offload, as datagram checksums are computed after segmentation. The option may also be set for individual sendmsg(2) calls by passing it as a cmsg(3). A value of zero disables the feature. This option should not be used in code intended to be portable.

UDP_GRO (since Linux 5.0)

Enables UDP receive offload. If enabled, the socket may receive multiple datagrams worth of data as a single large buffer, together with a cmsg(3) that holds the segment size. This option is the inverse of segmentation offload. It reduces receive cost by handling multiple datagrams worth of data as a single large packet in the kernel receive path, even when that exceeds MTU. This option should not be used in code intended to be portable.

### Ioctls
These ioctls can be accessed using ioctl(2). The correct syntax is:

```
int value;
error = ioctl(udp_socket, ioctl_type, &value);
```

FIONREAD (SIOCINQ)

Gets a pointer to an integer as argument. Returns the size of the next pending datagram in the integer in bytes, or 0 when no datagram is pending. Warning: Using FIONREAD, it is impossible to distinguish the case where no datagram is pending from the case where the next pending datagram contains zero bytes of data. It is safer to use select(2), poll(2), or epoll(7) to distinguish these cases.

TIOCOUTQ (SIOCOUTQ)

Returns the number of data bytes in the local send queue. Supported only with Linux 2.4 and above.

In addition, all ioctls documented in ip(7) and socket(7) are supported.

## ERRORS
All errors documented for socket(7) or ip(7) may be returned by a send or receive on a UDP socket.

ECONNREFUSED

No receiver was associated with the destination address. This might be caused by a previous packet sent over the socket.

## VERSIONS
IP_RECVERR is a new feature in Linux 2.2.

## SEE ALSO
ip(7), raw(7), socket(7), udplite(7)

The kernel source file Documentation/networking/ip-sysctl.txt.

RFC 768 for the User Datagram Protocol.

RFC 1122 for the host requirements.

RFC 1191 for a description of path MTU discovery.


udplite

title: udplite(7)

summary: Lightweight User Datagram Protocol

text:
# udplite(7)

## NAME
udplite - Lightweight User Datagram Protocol

## SYNOPSIS

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

```
sockfd = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
```

## DESCRIPTION
This is an implementation of the Lightweight User Datagram Protocol (UDP-Lite), as described in RFC 3828.

UDP-Lite is an extension of UDP (RFC 768) to support variable-length checksums. This has advantages for some types of multimedia transport that may be able to make use of slightly damaged datagrams, rather than having them discarded by lower-layer protocols.

The variable-length checksum coverage is set via a setsockopt(2) option. If this option is not set, the only difference from UDP is in using a different IP protocol identifier (IANA number 136).

The UDP-Lite implementation is a full extension of udp(7)—that is, it shares the same API and API behavior, and in addition offers two socket options to control the checksum coverage.

### Address format
UDP-Litev4 uses the sockaddr_in address format described in ip(7). UDP-Litev6 uses the sockaddr_in6 address format described in ipv6(7).

### Socket options
To set or get a UDP-Lite socket option, call getsockopt(2) to read or setsockopt(2) to write the option with the option level argument set to IPPROTO_UDPLITE. In addition, all IPPROTO_UDP socket options are valid on a UDP-Lite socket. See udp(7) for more information.

The following two options are specific to UDP-Lite.

UDPLITE_SEND_CSCOV

This option sets the sender checksum coverage and takes an int as argument, with a checksum coverage value in the range 0..2^16-1.

A value of 0 means that the entire datagram is always covered. Values from 1-7 are illegal (RFC 3828, 3.1) and are rounded up to the minimum coverage of 8.

With regard to IPv6 jumbograms (RFC 2675), the UDP-Litev6 checksum coverage is limited to the first 2^16-1 octets, as per RFC 3828, 3.5. Higher values are therefore silently truncated to 2^16-1. If in doubt, the current coverage value can always be queried using getsockopt(2).

UDPLITE_RECV_CSCOV

This is the receiver-side analogue and uses the same argument format and value range as UDPLITE_SEND_CSCOV. This option is not required to enable traffic with partial checksum coverage. Its function is that of a traffic filter: when enabled, it instructs the kernel to drop all packets which have a coverage less than the specified coverage value.

When the value of UDPLITE_RECV_CSCOV exceeds the actual packet coverage, incoming packets are silently dropped, but may generate a warning message in the system log.

## ERRORS
All errors documented for udp(7) may be returned. UDP-Lite does not add further errors.

## FILES
/proc/net/snmp

Basic UDP-Litev4 statistics counters.

/proc/net/snmp6

Basic UDP-Litev6 statistics counters.

## VERSIONS
UDP-Litev4/v6 first appeared in Linux 2.6.20.

## BUGS
Where glibc support is missing, the following definitions are needed:

```
#define IPPROTO_UDPLITE     136
#define UDPLITE_SEND_CSCOV  10
#define UDPLITE_RECV_CSCOV  11
```

## SEE ALSO
ip(7), ipv6(7), socket(7), udp(7)

RFC 3828 for the Lightweight User Datagram Protocol (UDP-Lite).

Documentation/networking/udplite.txt in the Linux kernel source tree


unicode

title: unicode(7)

summary: universal character set

text:
# unicode(7)

## NAME
unicode - universal character set

## DESCRIPTION
The international standard ISO/IEC 10646 defines the Universal Character Set (UCS). UCS contains all characters of all other character set standards. It also guarantees "round-trip compatibility"; in other words, conversion tables can be built such that no information is lost when a string is converted from any other encoding to UCS and back.

UCS contains the characters required to represent practically all known languages. This includes not only the Latin, Greek, Cyrillic, Hebrew, Arabic, Armenian, and Georgian scripts, but also Chinese, Japanese and Korean Han ideographs as well as scripts such as Hiragana, Katakana, Hangul, Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam, Thai, Lao, Khmer, Bopomofo, Tibetan, Runic, Ethiopic, Canadian Syllabics, Cherokee, Mongolian, Ogham, Myanmar, Sinhala, Thaana, Yi, and others. For scripts not yet covered, research on how to best encode them for computer usage is still going on and they will be added eventually. This might eventually include not only Hieroglyphs and various historic Indo-European languages, but even some selected artistic scripts such as Tengwar, Cirth, and Klingon. UCS also covers a large number of graphical, typographical, mathematical, and scientific symbols, including those provided by TeX, Postscript, APL, MS-DOS, MS-Windows, Macintosh, OCR fonts, as well as many word processing and publishing systems, and more are being added.

The UCS standard (ISO/IEC 10646) describes a 31-bit character set architecture consisting of 128 24-bit groups, each divided into 256 16-bit planes made up of 256 8-bit rows with 256 column positions, one for each character. Part 1 of the standard (ISO/IEC 10646-1) defines the first 65534 code positions (0x0000 to 0xfffd), which form the Basic Multilingual Plane (BMP), that is plane 0 in group 0. Part 2 of the standard (ISO/IEC 10646-2) adds characters to group 0 outside the BMP in several supplementary planes in the range 0x10000 to 0x10ffff. There are no plans to add characters beyond 0x10ffff to the standard, therefore of the entire code space, only a small fraction of group 0 will ever be actually used in the foreseeable future. The BMP contains all characters found in the commonly used other character sets. The supplemental planes added by ISO/IEC 10646-2 cover only more exotic characters for special scientific, dictionary printing, publishing industry, higher-level protocol and enthusiast needs.

The representation of each UCS character as a 2-byte word is referred to as the UCS-2 form (only for BMP characters), whereas UCS-4 is the representation of each character by a 4-byte word. In addition, there exist two encoding forms UTF-8 for backward compatibility with ASCII processing software and UTF-16 for the backward-compatible handling of non-BMP characters up to 0x10ffff by UCS-2 software.

The UCS characters 0x0000 to 0x007f are identical to those of the classic US-ASCII character set and the characters in the range 0x0000 to 0x00ff are identical to those in ISO 8859-1 (Latin-1).

### Combining characters
Some code points in UCS have been assigned to combining characters. These are similar to the nonspacing accent keys on a typewriter. A combining character just adds an accent to the previous character. The most important accented characters have codes of their own in UCS, however, the combining character mechanism allows us to add accents and other diacritical marks to any character. The combining characters always follow the character which they modify. For example, the German character Umlaut-A ("Latin capital letter A with diaeresis") can either be represented by the precomposed UCS code 0x00c4, or alternatively as the combination of a normal "Latin capital letter A" followed by a "combining diaeresis": 0x0041 0x0308.

Combining characters are essential for instance for encoding the Thai script or for mathematical typesetting and users of the International Phonetic Alphabet.

### Implementation levels
As not all systems are expected to support advanced mechanisms like combining characters, ISO/IEC 10646-1 specifies the following three implementation levels of UCS:

Level 1

Combining characters and Hangul Jamo (a variant encoding of the Korean script, where a Hangul syllable glyph is coded as a triplet or pair of vowel/consonant codes) are not supported.

Level 2

In addition to level 1, combining characters are now allowed for some languages where they are essential (e.g., Thai, Lao, Hebrew, Arabic, Devanagari, Malayalam).

Level 3

All UCS characters are supported.

The Unicode 3.0 Standard published by the Unicode Consortium contains exactly the UCS Basic Multilingual Plane at implementation level 3, as described in ISO/IEC 10646-1:2000. Unicode 3.1 added the supplemental planes of ISO/IEC 10646-2. The Unicode standard and technical reports published by the Unicode Consortium provide much additional information on the semantics and recommended usages of various characters. They provide guidelines and algorithms for editing, sorting, comparing, normalizing, converting, and displaying Unicode strings.

### Unicode under Linux
Under GNU/Linux, the C type wchar_t is a signed 32-bit integer type. Its values are always interpreted by the C library as UCS code values (in all locales), a convention that is signaled by the GNU C library to applications by defining the constant __STDC_ISO_10646__ as specified in the ISO C99 standard.

UCS/Unicode can be used just like ASCII in input/output streams, terminal communication, plaintext files, filenames, and environment variables in the ASCII compatible UTF-8 multibyte encoding. To signal the use of UTF-8 as the character encoding to all applications, a suitable locale has to be selected via environment variables (e.g., "LANG=en_GB.UTF-8").

The nl_langinfo(CODESET) function returns the name of the selected encoding. Library functions such as wctomb(3) and mbsrtowcs(3) can be used to transform the internal wchar_t characters and strings into the system character encoding and back and wcwidth(3) tells how many positions (0–2) the cursor is advanced by the output of a character.

### Private Use Areas (PUA)
In the Basic Multilingual Plane, the range 0xe000 to 0xf8ff will never be assigned to any characters by the standard and is reserved for private usage. For the Linux community, this private area has been subdivided further into the range 0xe000 to 0xefff which can be used individually by any end-user and the Linux zone in the range 0xf000 to 0xf8ff where extensions are coordinated among all Linux users. The registry of the characters assigned to the Linux zone is maintained by LANANA and the registry itself is Documentation/admin-guide/unicode.rst in the Linux kernel sources (or Documentation/unicode.txt before Linux 4.10).

Two other planes are reserved for private usage, plane 15 (Supplementary Private Use Area-A, range 0xf0000 to 0xffffd) and plane 16 (Supplementary Private Use Area-B, range 0x100000 to 0x10fffd).

### Literature
•

Information technology — Universal Multiple-Octet Coded Character Set (UCS) — Part 1: Architecture and Basic Multilingual Plane. International Standard ISO/IEC 10646-1, International Organization for Standardization, Geneva, 2000.

This is the official specification of UCS. Available from http://www.iso.ch/.

•

The Unicode Standard, Version 3.0. The Unicode Consortium, Addison-Wesley, Reading, MA, 2000, ISBN 0-201-61633-5.

•

S. Harbison, G. Steele. C: A Reference Manual. Fourth edition, Prentice Hall, Englewood Cliffs, 1995, ISBN 0-13-326224-3.

A good reference book about the C programming language. The fourth edition covers the 1994 Amendment 1 to the ISO C90 standard, which adds a large number of new C library functions for handling wide and multibyte character encodings, but it does not yet cover ISO C99, which improved wide and multibyte character support even further.

•

Unicode Technical Reports.

http://www.unicode.org/reports/

•

Markus Kuhn: UTF-8 and Unicode FAQ for UNIX/Linux.

http://www.cl.cam.ac.uk/~mgk25/unicode.html

•

Bruno Haible: Unicode HOWTO.

http://www.tldp.org/HOWTO/Unicode-HOWTO.html

## SEE ALSO
locale(1), setlocale(3), charsets(7), utf-8(7)


units

title: units(7)

summary: decimal and binary prefixes

text:
# units(7)

## NAME
units - decimal and binary prefixes

## DESCRIPTION

### Decimal prefixes
The SI system of units uses prefixes that indicate powers of ten. A kilometer is 1000 meter, and a megawatt is 1000000 watt. Below the standard prefixes.

Prefix

Name

Value

q

quecto

10^-30 = 0.000000000000000000000000000001

r

ronto

10^-27 = 0.000000000000000000000000001

y

yocto

10^-24 = 0.000000000000000000000001

z

zepto

10^-21 = 0.000000000000000000001

a

atto

10^-18 = 0.000000000000000001

f

femto

10^-15 = 0.000000000000001

p

pico

10^-12 = 0.000000000001

n

nano

10^-9 = 0.000000001

µ

micro

10^-6 = 0.000001

m

milli

10^-3 = 0.001

c

centi

10^-2 = 0.01

d

deci

10^-1 = 0.1

da

deka

10^ 1 = 10

h

hecto

10^ 2 = 100

k

kilo

10^ 3 = 1000

M

mega

10^ 6 = 1000000

G

giga

10^ 9 = 1000000000

T

tera

10^12 = 1000000000000

P

peta

10^15 = 1000000000000000

E

exa

10^18 = 1000000000000000000

Z

zetta

10^21 = 1000000000000000000000

Y

yotta

10^24 = 1000000000000000000000000

R

ronna

10^27 = 1000000000000000000000000000

Q

quetta

10^30 = 1000000000000000000000000000000

The symbol for micro is the Greek letter mu, often written u in an ASCII context where this Greek letter is not available.

### Binary prefixes
The binary prefixes resemble the decimal ones, but have an additional 'i' (and "Ki" starts with a capital 'K'). The names are formed by taking the first syllable of the names of the decimal prefix with roughly the same size, followed by "bi" for "binary".

Prefix

Name

Value

Ki

kibi

2^10 = 1024

Mi

mebi

2^20 = 1048576

Gi

gibi

2^30 = 1073741824

Ti

tebi

2^40 = 1099511627776

Pi

pebi

2^50 = 1125899906842624

Ei

exbi

2^60 = 1152921504606846976

Zi

zebi

2^70 = 1180591620717411303424

Yi

yobi

2^80 = 1208925819614629174706176

### Discussion
Before these binary prefixes were introduced, it was fairly common to use k=1000 and K=1024, just like b=bit, B=byte. Unfortunately, the M is capital already, and cannot be capitalized to indicate binary-ness.

At first that didn't matter too much, since memory modules and disks came in sizes that were powers of two, so everyone knew that in such contexts "kilobyte" and "megabyte" meant 1024 and 1048576 bytes, respectively. What originally was a sloppy use of the prefixes "kilo" and "mega" started to become regarded as the "real true meaning" when computers were involved. But then disk technology changed, and disk sizes became arbitrary numbers. After a period of uncertainty all disk manufacturers settled on the standard, namely k=1000, M=1000 k, G=1000 M.

The situation was messy: in the 14k4 modems, k=1000; in the 1.44 MB diskettes, M=1024000; and so on. In 1998 the IEC approved the standard that defines the binary prefixes given above, enabling people to be precise and unambiguous.

Thus, today, MB = 1000000 B and MiB = 1048576 B.

In the free software world programs are slowly being changed to conform. When the Linux kernel boots and says

```
hda: 120064896 sectors (61473 MB) w/2048KiB Cache
```

the MB are megabytes and the KiB are kibibytes.

## SEE ALSO
The International System of Units.


unix

title: unix(7)

text:
# unix(7)

## NAME
unix - sockets for local interprocess communication

## SYNOPSIS

```
#include <sys/socket.h>
#include <sys/un.h>
```

```
unix_socket = socket(AF_UNIX, type, 0);
error = socketpair(AF_UNIX, type, 0, int *sv);
```

## DESCRIPTION
The AF_UNIX (also known as AF_LOCAL) socket family is used to communicate between processes on the same machine efficiently. Traditionally, UNIX domain sockets can be either unnamed, or bound to a filesystem pathname (marked as being of type socket). Linux also supports an abstract namespace which is independent of the filesystem.

Valid socket types in the UNIX domain are: SOCK_STREAM, for a stream-oriented socket; SOCK_DGRAM, for a datagram-oriented socket that preserves message boundaries (as on most UNIX implementations, UNIX domain datagram sockets are always reliable and don't reorder datagrams); and (since Linux 2.6.4) SOCK_SEQPACKET, for a sequenced-packet socket that is connection-oriented, preserves message boundaries, and delivers messages in the order that they were sent.

UNIX domain sockets support passing file descriptors or process credentials to other processes using ancillary data.

### Address format
A UNIX domain socket address is represented in the following structure:

```
struct sockaddr_un {

    sa_family_t sun_family;               /* AF_UNIX */

    char        sun_path[108];            /* Pathname */
};
```

The sun_family field always contains AF_UNIX. On Linux, sun_path is 108 bytes in size; see also BUGS, below.

Various systems calls (for example, bind(2), connect(2), and sendto(2)) take a sockaddr_un argument as input. Some other system calls (for example, getsockname(2), getpeername(2), recvfrom(2), and accept(2)) return an argument of this type.

Three types of address are distinguished in the sockaddr_un structure:

pathname

a UNIX domain socket can be bound to a null-terminated filesystem pathname using bind(2). When the address of a pathname socket is returned (by one of the system calls noted above), its length is

```
offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1

```

and sun_path contains the null-terminated pathname. (On Linux, the above offsetof() expression equates to the same value as sizeof(sa_family_t), but some other implementations include other fields before sun_path, so the offsetof() expression more portably describes the size of the address structure.)

For further details of pathname sockets, see below.

unnamed

A stream socket that has not been bound to a pathname using bind(2) has no name. Likewise, the two sockets created by socketpair(2) are unnamed. When the address of an unnamed socket is returned, its length is sizeof(sa_family_t), and sun_path should not be inspected.

abstract

an abstract socket address is distinguished (from a pathname socket) by the fact that sun_path[0] is a null byte ('\0'). The socket's address in this namespace is given by the additional bytes in sun_path that are covered by the specified length of the address structure. (Null bytes in the name have no special significance.) The name has no connection with filesystem pathnames. When the address of an abstract socket is returned, the returned addrlen is greater than sizeof(sa_family_t) (i.e., greater than 2), and the name of the socket is contained in the first (addrlen - sizeof(sa_family_t)) bytes of sun_path.

### Pathname sockets
When binding a socket to a pathname, a few rules should be observed for maximum portability and ease of coding:

•

The pathname in sun_path should be null-terminated.

•

The length of the pathname, including the terminating null byte, should not exceed the size of sun_path.

•

The addrlen argument that describes the enclosing sockaddr_un structure should have a value of at least:

```
offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1

```

or, more simply, addrlen can be specified as sizeof(struct sockaddr_un).

There is some variation in how implementations handle UNIX domain socket addresses that do not follow the above rules. For example, some (but not all) implementations append a null terminator if none is present in the supplied sun_path.

When coding portable applications, keep in mind that some implementations have sun_path as short as 92 bytes.

Various system calls (accept(2), recvfrom(2), getsockname(2), getpeername(2)) return socket address structures. When applied to UNIX domain sockets, the value-result addrlen argument supplied to the call should be initialized as above. Upon return, the argument is set to indicate the actual size of the address structure. The caller should check the value returned in this argument: if the output value exceeds the input value, then there is no guarantee that a null terminator is present in sun_path. (See BUGS.)

### Pathname socket ownership and permissions
In the Linux implementation, pathname sockets honor the permissions of the directory they are in. Creation of a new socket fails if the process does not have write and search (execute) permission on the directory in which the socket is created.

On Linux, connecting to a stream socket object requires write permission on that socket; sending a datagram to a datagram socket likewise requires write permission on that socket. POSIX does not make any statement about the effect of the permissions on a socket file, and on some systems (e.g., older BSDs), the socket permissions are ignored. Portable programs should not rely on this feature for security.

When creating a new socket, the owner and group of the socket file are set according to the usual rules. The socket file has all permissions enabled, other than those that are turned off by the process umask(2).

The owner, group, and permissions of a pathname socket can be changed (using chown(2) and chmod(2)).

### Abstract sockets
Socket permissions have no meaning for abstract sockets: the process umask(2) has no effect when binding an abstract socket, and changing the ownership and permissions of the object (via fchown(2) and fchmod(2)) has no effect on the accessibility of the socket.

Abstract sockets automatically disappear when all open references to the socket are closed.

The abstract socket namespace is a nonportable Linux extension.

### Socket options
For historical reasons, these socket options are specified with a SOL_SOCKET type even though they are AF_UNIX specific. They can be set with setsockopt(2) and read with getsockopt(2) by specifying SOL_SOCKET as the socket family.

SO_PASSCRED

Enabling this socket option causes receipt of the credentials of the sending process in an SCM_CREDENTIALS ancillary message in each subsequently received message. The returned credentials are those specified by the sender using SCM_CREDENTIALS, or a default that includes the sender's PID, real user ID, and real group ID, if the sender did not specify SCM_CREDENTIALS ancillary data.

When this option is set and the socket is not yet connected, a unique name in the abstract namespace will be generated automatically.

The value given as an argument to setsockopt(2) and returned as the result of getsockopt(2) is an integer boolean flag.

SO_PASSSEC

Enables receiving of the SELinux security label of the peer socket in an ancillary message of type SCM_SECURITY (see below).

The value given as an argument to setsockopt(2) and returned as the result of getsockopt(2) is an integer boolean flag.

The SO_PASSSEC option is supported for UNIX domain datagram sockets since Linux 2.6.18; support for UNIX domain stream sockets was added in Linux 4.2.

SO_PEEK_OFF

See socket(7).

SO_PEERCRED

This read-only socket option returns the credentials of the peer process connected to this socket. The returned credentials are those that were in effect at the time of the call to connect(2) or socketpair(2).

The argument to getsockopt(2) is a pointer to a ucred structure; define the _GNU_SOURCE feature test macro to obtain the definition of that structure from <sys/socket.h>.

The use of this option is possible only for connected AF_UNIX stream sockets and for AF_UNIX stream and datagram socket pairs created using socketpair(2).

SO_PEERSEC

This read-only socket option returns the security context of the peer socket connected to this socket. By default, this will be the same as the security context of the process that created the peer socket unless overridden by the policy or by a process with the required permissions.

The argument to getsockopt(2) is a pointer to a buffer of the specified length in bytes into which the security context string will be copied. If the buffer length is less than the length of the security context string, then getsockopt(2) returns -1, sets errno to ERANGE, and returns the required length via optlen. The caller should allocate at least NAME_MAX bytes for the buffer initially, although this is not guaranteed to be sufficient. Resizing the buffer to the returned length and retrying may be necessary.

The security context string may include a terminating null character in the returned length, but is not guaranteed to do so: a security context "foo" might be represented as either {'f','o','o'} of length 3 or {'f','o','o','\0'} of length 4, which are considered to be interchangeable. The string is printable, does not contain non-terminating null characters, and is in an unspecified encoding (in particular, it is not guaranteed to be ASCII or UTF-8).

The use of this option for sockets in the AF_UNIX address family is supported since Linux 2.6.2 for connected stream sockets, and since Linux 4.18 also for stream and datagram socket pairs created using socketpair(2).

### Autobind feature
If a bind(2) call specifies addrlen as sizeof(sa_family_t), or the SO_PASSCRED socket option was specified for a socket that was not explicitly bound to an address, then the socket is autobound to an abstract address. The address consists of a null byte followed by 5 bytes in the character set [0-9a-f]. Thus, there is a limit of 2^20 autobind addresses. (From Linux 2.1.15, when the autobind feature was added, 8 bytes were used, and the limit was thus 2^32 autobind addresses. The change to 5 bytes came in Linux 2.3.15.)

### Sockets API
The following paragraphs describe domain-specific details and unsupported features of the sockets API for UNIX domain sockets on Linux.

UNIX domain sockets do not support the transmission of out-of-band data (the MSG_OOB flag for send(2) and recv(2)).

The send(2) MSG_MORE flag is not supported by UNIX domain sockets.

Before Linux 3.4, the use of MSG_TRUNC in the flags argument of recv(2) was not supported by UNIX domain sockets.

The SO_SNDBUF socket option does have an effect for UNIX domain sockets, but the SO_RCVBUF option does not. For datagram sockets, the SO_SNDBUF value imposes an upper limit on the size of outgoing datagrams. This limit is calculated as the doubled (see socket(7)) option value less 32 bytes used for overhead.

### Ancillary messages
Ancillary data is sent and received using sendmsg(2) and recvmsg(2). For historical reasons, the ancillary message types listed below are specified with a SOL_SOCKET type even though they are AF_UNIX specific. To send them, set the cmsg_level field of the struct cmsghdr to SOL_SOCKET and the cmsg_type field to the type. For more information, see cmsg(3).

SCM_RIGHTS

Send or receive a set of open file descriptors from another process. The data portion contains an integer array of the file descriptors.

Commonly, this operation is referred to as "passing a file descriptor" to another process. However, more accurately, what is being passed is a reference to an open file description (see open(2)), and in the receiving process it is likely that a different file descriptor number will be used. Semantically, this operation is equivalent to duplicating (dup(2)) a file descriptor into the file descriptor table of another process.

If the buffer used to receive the ancillary data containing file descriptors is too small (or is absent), then the ancillary data is truncated (or discarded) and the excess file descriptors are automatically closed in the receiving process.

If the number of file descriptors received in the ancillary data would cause the process to exceed its RLIMIT_NOFILE resource limit (see getrlimit(2)), the excess file descriptors are automatically closed in the receiving process.

The kernel constant SCM_MAX_FD defines a limit on the number of file descriptors in the array. Attempting to send an array larger than this limit causes sendmsg(2) to fail with the error EINVAL. SCM_MAX_FD has the value 253 (or 255 before Linux 2.6.38).

SCM_CREDENTIALS

Send or receive UNIX credentials. This can be used for authentication. The credentials are passed as a struct ucred ancillary message. This structure is defined in <sys/socket.h> as follows:

```
struct ucred {

    pid_t pid;    /* Process ID of the sending process */

    uid_t uid;    /* User ID of the sending process */

    gid_t gid;    /* Group ID of the sending process */
};

```

Since glibc 2.8, the _GNU_SOURCE feature test macro must be defined (before including any header files) in order to obtain the definition of this structure.

The credentials which the sender specifies are checked by the kernel. A privileged process is allowed to specify values that do not match its own. The sender must specify its own process ID (unless it has the capability CAP_SYS_ADMIN, in which case the PID of any existing process may be specified), its real user ID, effective user ID, or saved set-user-ID (unless it has CAP_SETUID), and its real group ID, effective group ID, or saved set-group-ID (unless it has CAP_SETGID).

To receive a struct ucred message, the SO_PASSCRED option must be enabled on the socket.

SCM_SECURITY

Receive the SELinux security context (the security label) of the peer socket. The received ancillary data is a null-terminated string containing the security context. The receiver should allocate at least NAME_MAX bytes in the data portion of the ancillary message for this data.

To receive the security context, the SO_PASSSEC option must be enabled on the socket (see above).

When sending ancillary data with sendmsg(2), only one item of each of the above types may be included in the sent message.

At least one byte of real data should be sent when sending ancillary data. On Linux, this is required to successfully send ancillary data over a UNIX domain stream socket. When sending ancillary data over a UNIX domain datagram socket, it is not necessary on Linux to send any accompanying real data. However, portable applications should also include at least one byte of real data when sending ancillary data over a datagram socket.

When receiving from a stream socket, ancillary data forms a kind of barrier for the received data. For example, suppose that the sender transmits as follows:

(1)

sendmsg(2) of four bytes, with no ancillary data.

(2)

sendmsg(2) of one byte, with ancillary data.

(3)

sendmsg(2) of four bytes, with no ancillary data.

Suppose that the receiver now performs recvmsg(2) calls each with a buffer size of 20 bytes. The first call will receive five bytes of data, along with the ancillary data sent by the second sendmsg(2) call. The next call will receive the remaining four bytes of data.

If the space allocated for receiving incoming ancillary data is too small then the ancillary data is truncated to the number of headers that will fit in the supplied buffer (or, in the case of an SCM_RIGHTS file descriptor list, the list of file descriptors may be truncated). If no buffer is provided for incoming ancillary data (i.e., the msg_control field of the msghdr structure supplied to recvmsg(2) is NULL), then the incoming ancillary data is discarded. In both of these cases, the MSG_CTRUNC flag will be set in the msg.msg_flags value returned by recvmsg(2).

### Ioctls
The following ioctl(2) calls return information in value. The correct syntax is:

```
int value;
error = ioctl(unix_socket, ioctl_type, &value);
```

ioctl_type can be:

SIOCINQ

For SOCK_STREAM sockets, this call returns the number of unread bytes in the receive buffer. The socket must not be in LISTEN state, otherwise an error (EINVAL) is returned. SIOCINQ is defined in <linux/sockios.h>. Alternatively, you can use the synonymous FIONREAD, defined in <sys/ioctl.h>. For SOCK_DGRAM sockets, the returned value is the same as for Internet domain datagram sockets; see udp(7).

## ERRORS
EADDRINUSE

The specified local address is already in use or the filesystem socket object already exists.

EBADF

This error can occur for sendmsg(2) when sending a file descriptor as ancillary data over a UNIX domain socket (see the description of SCM_RIGHTS, above), and indicates that the file descriptor number that is being sent is not valid (e.g., it is not an open file descriptor).

ECONNREFUSED

The remote address specified by connect(2) was not a listening socket. This error can also occur if the target pathname is not a socket.

ECONNRESET

Remote socket was unexpectedly closed.

EFAULT

User memory address was not valid.

EINVAL

Invalid argument passed. A common cause is that the value AF_UNIX was not specified in the sun_type field of passed addresses, or the socket was in an invalid state for the applied operation.

EISCONN

connect(2) called on an already connected socket or a target address was specified on a connected socket.

ENFILE

The system-wide limit on the total number of open files has been reached.

ENOENT

The pathname in the remote address specified to connect(2) did not exist.

ENOMEM

Out of memory.

ENOTCONN

Socket operation needs a target address, but the socket is not connected.

EOPNOTSUPP

Stream operation called on non-stream oriented socket or tried to use the out-of-band data option.

EPERM

The sender passed invalid credentials in the struct ucred.

EPIPE

Remote socket was closed on a stream socket. If enabled, a SIGPIPE is sent as well. This can be avoided by passing the MSG_NOSIGNAL flag to send(2) or sendmsg(2).

EPROTONOSUPPORT

Passed protocol is not AF_UNIX.

EPROTOTYPE

Remote socket does not match the local socket type (SOCK_DGRAM versus SOCK_STREAM).

ESOCKTNOSUPPORT

Unknown socket type.

ESRCH

While sending an ancillary message containing credentials (SCM_CREDENTIALS), the caller specified a PID that does not match any existing process.

ETOOMANYREFS

This error can occur for sendmsg(2) when sending a file descriptor as ancillary data over a UNIX domain socket (see the description of SCM_RIGHTS, above). It occurs if the number of "in-flight" file descriptors exceeds the RLIMIT_NOFILE resource limit and the caller does not have the CAP_SYS_RESOURCE capability. An in-flight file descriptor is one that has been sent using sendmsg(2) but has not yet been accepted in the recipient process using recvmsg(2).

This error is diagnosed since mainline Linux 4.5 (and in some earlier kernel versions where the fix has been backported). In earlier kernel versions, it was possible to place an unlimited number of file descriptors in flight, by sending each file descriptor with sendmsg(2) and then closing the file descriptor so that it was not accounted against the RLIMIT_NOFILE resource limit.

Other errors can be generated by the generic socket layer or by the filesystem while generating a filesystem socket object. See the appropriate manual pages for more information.

## VERSIONS
SCM_CREDENTIALS and the abstract namespace were introduced with Linux 2.2 and should not be used in portable programs. (Some BSD-derived systems also support credential passing, but the implementation details differ.)

## NOTES
Binding to a socket with a filename creates a socket in the filesystem that must be deleted by the caller when it is no longer needed (using unlink(2)). The usual UNIX close-behind semantics apply; the socket can be unlinked at any time and will be finally removed from the filesystem when the last reference to it is closed.

To pass file descriptors or credentials over a SOCK_STREAM socket, you must send or receive at least one byte of nonancillary data in the same sendmsg(2) or recvmsg(2) call.

UNIX domain stream sockets do not support the notion of out-of-band data.

## BUGS
When binding a socket to an address, Linux is one of the implementations that appends a null terminator if none is supplied in sun_path. In most cases this is unproblematic: when the socket address is retrieved, it will be one byte longer than that supplied when the socket was bound. However, there is one case where confusing behavior can result: if 108 non-null bytes are supplied when a socket is bound, then the addition of the null terminator takes the length of the pathname beyond sizeof(sun_path). Consequently, when retrieving the socket address (for example, via accept(2)), if the input addrlen argument for the retrieving call is specified as sizeof(struct sockaddr_un), then the returned address structure won't have a null terminator in sun_path.

In addition, some implementations don't require a null terminator when binding a socket (the addrlen argument is used to determine the length of sun_path) and when the socket address is retrieved on these implementations, there is no null terminator in sun_path.

Applications that retrieve socket addresses can (portably) code to handle the possibility that there is no null terminator in sun_path by respecting the fact that the number of valid bytes in the pathname is:

```
strnlen(addr.sun_path, addrlen - offsetof(sockaddr_un, sun_path))
```

Alternatively, an application can retrieve the socket address by allocating a buffer of size sizeof(struct sockaddr_un)+1 that is zeroed out before the retrieval. The retrieving call can specify addrlen as sizeof(struct sockaddr_un), and the extra zero byte ensures that there will be a null terminator for the string returned in sun_path:

```
void *addrp;
addrlen = sizeof(struct sockaddr_un);
addrp = malloc(addrlen + 1);
if (addrp == NULL)

    /* Handle error */ ;
memset(addrp, 0, addrlen + 1);
if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == -1)

    /* handle error */ ;
printf("sun_path = %s\n", ((struct sockaddr_un *) addrp)->sun_path);
```

This sort of messiness can be avoided if it is guaranteed that the applications that create pathname sockets follow the rules outlined above under Pathname sockets.

## EXAMPLES
The following code demonstrates the use of sequenced-packet sockets for local interprocess communication. It consists of two programs. The server program waits for a connection from the client program. The client sends each of its command-line arguments in separate messages. The server treats the incoming messages as integers and adds them up. The client sends the command string "END". The server sends back a message containing the sum of the client's integers. The client prints the sum and exits. The server waits for the next client to connect. To stop the server, the client is called with the command-line argument "DOWN".

The following output was recorded while running the server in the background and repeatedly executing the client. Execution of the server program ends when it receives the "DOWN" command.

### Example output

```
$ ./server &
[1] 25887
$ ./client 3 4
Result = 7
$ ./client 11 -5
Result = 6
$ ./client DOWN
Result = 0
[1]+  Done                    ./server
$
```

### Program source

```
/*

 * File connection.h

 */
#define SOCKET_NAME "/tmp/9Lq7BNBnBycd6nxy.socket"
#define BUFFER_SIZE 12
/*

 * File server.c

 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/socket.h>
#include <sys/un.h>
#include <unistd.h>
#include "connection.h"
int
main(int argc, char *argv[])
{

    struct sockaddr_un name;

    int down_flag = 0;

    int ret;

    int connection_socket;

    int data_socket;

    int result;

    char buffer[BUFFER_SIZE];

    /* Create local socket. */

    connection_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0);

    if (connection_socket == -1) {

        perror("socket");

        exit(EXIT_FAILURE);

    }

    /*

     * For portability clear the whole structure, since some

     * implementations have additional (nonstandard) fields in

     * the structure.

     */

    memset(&name, 0, sizeof(name));

    /* Bind socket to socket name. */

    name.sun_family = AF_UNIX;

    strncpy(name.sun_path, SOCKET_NAME, sizeof(name.sun_path) - 1);

    ret = bind(connection_socket, (const struct sockaddr *) &name,

               sizeof(name));

    if (ret == -1) {

        perror("bind");

        exit(EXIT_FAILURE);

    }

    /*

     * Prepare for accepting connections. The backlog size is set

     * to 20. So while one request is being processed other requests

     * can be waiting.

     */

    ret = listen(connection_socket, 20);

    if (ret == -1) {

        perror("listen");

        exit(EXIT_FAILURE);

    }

    /* This is the main loop for handling connections. */

    for (;;) {

        /* Wait for incoming connection. */

        data_socket = accept(connection_socket, NULL, NULL);

        if (data_socket == -1) {

            perror("accept");

            exit(EXIT_FAILURE);

        }

        result = 0;

        for (;;) {

            /* Wait for next data packet. */

            ret = read(data_socket, buffer, sizeof(buffer));

            if (ret == -1) {

                perror("read");

                exit(EXIT_FAILURE);

            }

            /* Ensure buffer is 0-terminated. */

            buffer[sizeof(buffer) - 1] = 0;

            /* Handle commands. */

            if (!strncmp(buffer, "DOWN", sizeof(buffer))) {

                down_flag = 1;

                break;

            }

            if (!strncmp(buffer, "END", sizeof(buffer))) {

                break;

            }

            /* Add received summand. */

            result += atoi(buffer);

        }

        /* Send result. */

        sprintf(buffer, "%d", result);

        ret = write(data_socket, buffer, sizeof(buffer));

        if (ret == -1) {

            perror("write");

            exit(EXIT_FAILURE);

        }

        /* Close socket. */

        close(data_socket);

        /* Quit on DOWN command. */

        if (down_flag) {

            break;

        }

    }

    close(connection_socket);

    /* Unlink the socket. */

    unlink(SOCKET_NAME);

    exit(EXIT_SUCCESS);
}
/*

 * File client.c

 */
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/socket.h>
#include <sys/un.h>
#include <unistd.h>
#include "connection.h"
int
main(int argc, char *argv[])
{

    struct sockaddr_un addr;

    int ret;

    int data_socket;

    char buffer[BUFFER_SIZE];

    /* Create local socket. */

    data_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0);

    if (data_socket == -1) {

        perror("socket");

        exit(EXIT_FAILURE);

    }

    /*

     * For portability clear the whole structure, since some

     * implementations have additional (nonstandard) fields in

     * the structure.

     */

    memset(&addr, 0, sizeof(addr));

    /* Connect socket to socket address. */

    addr.sun_family = AF_UNIX;

    strncpy(addr.sun_path, SOCKET_NAME, sizeof(addr.sun_path) - 1);

    ret = connect(data_socket, (const struct sockaddr *) &addr,

                   sizeof(addr));

    if (ret == -1) {

        fprintf(stderr, "The server is down.\n");

        exit(EXIT_FAILURE);

    }

    /* Send arguments. */

    for (size_t i = 1; i < argc; ++i) {

        ret = write(data_socket, argv[i], strlen(argv[i]) + 1);

        if (ret == -1) {

            perror("write");

            break;

        }

    }

    /* Request result. */

    strcpy(buffer, "END");

    ret = write(data_socket, buffer, strlen(buffer) + 1);

    if (ret == -1) {

        perror("write");

        exit(EXIT_FAILURE);

    }

    /* Receive result. */

    ret = read(data_socket, buffer, sizeof(buffer));

    if (ret == -1) {

        perror("read");

        exit(EXIT_FAILURE);

    }

    /* Ensure buffer is 0-terminated. */

    buffer[sizeof(buffer) - 1] = 0;

    printf("Result = %s\n", buffer);

    /* Close socket. */

    close(data_socket);

    exit(EXIT_SUCCESS);
}
```

For examples of the use of SCM_RIGHTS, see cmsg(3) and seccomp_unotify(2).

## SEE ALSO
recvmsg(2), sendmsg(2), socket(2), socketpair(2), cmsg(3), capabilities(7), credentials(7), socket(7), udp(7)


uri

title: uri(7)

text:
# uri(7)

## NAME
uri, url, urn - uniform resource identifier (URI), including a URL or URN

## SYNOPSIS
URI =

[ absoluteURI | relativeURI ] [ "#" fragment ]

absoluteURI =

scheme ":" ( hierarchical_part | opaque_part )

relativeURI =

( net_path | absolute_path | relative_path ) [ "?" query ]

scheme =

"http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" | "file" | "ftp" | "man" | "info" | "whatis" | "ldap" | "wais" | ...

hierarchical_part =

( net_path | absolute_path ) [ "?" query ]

net_path =

"//" authority [ absolute_path ]

absolute_path =

"/" path_segments

relative_path =

relative_segment [ absolute_path ]

## DESCRIPTION
A Uniform Resource Identifier (URI) is a short string of characters identifying an abstract or physical resource (for example, a web page). A Uniform Resource Locator (URL) is a URI that identifies a resource through its primary access mechanism (e.g., its network "location"), rather than by name or some other attribute of that resource. A Uniform Resource Name (URN) is a URI that must remain globally unique and persistent even when the resource ceases to exist or becomes unavailable.

URIs are the standard way to name hypertext link destinations for tools such as web browsers. The string "http://www.kernel.org" is a URL (and thus it is also a URI). Many people use the term URL loosely as a synonym for URI (though technically URLs are a subset of URIs).

URIs can be absolute or relative. An absolute identifier refers to a resource independent of context, while a relative identifier refers to a resource by describing the difference from the current context. Within a relative path reference, the complete path segments "." and ".." have special meanings: "the current hierarchy level" and "the level above this hierarchy level", respectively, just like they do in UNIX-like systems. A path segment which contains a colon character can't be used as the first segment of a relative URI path (e.g., "this:that"), because it would be mistaken for a scheme name; precede such segments with ./ (e.g., "./this:that"). Note that descendants of MS-DOS (e.g., Microsoft Windows) replace devicename colons with the vertical bar ("|") in URIs, so "C:" becomes "C|".

A fragment identifier, if included, refers to a particular named portion (fragment) of a resource; text after a '#' identifies the fragment. A URI beginning with '#' refers to that fragment in the current resource.

### Usage
There are many different URI schemes, each with specific additional rules and meanings, but they are intentionally made to be as similar as possible. For example, many URL schemes permit the authority to be the following format, called here an ip_server (square brackets show what's optional):

ip_server = [user [ : password ] @ ] host [ : port]

This format allows you to optionally insert a username, a user plus password, and/or a port number. The host is the name of the host computer, either its name as determined by DNS or an IP address (numbers separated by periods). Thus the URI <http://fred:fredpassword@example.com:8080/> logs into a web server on host example.com as fred (using fredpassword) using port 8080. Avoid including a password in a URI if possible because of the many security risks of having a password written down. If the URL supplies a username but no password, and the remote server requests a password, the program interpreting the URL should request one from the user.

Here are some of the most common schemes in use on UNIX-like systems that are understood by many tools. Note that many tools using URIs also have internal schemes or specialized schemes; see those tools' documentation for information on those schemes.

http - Web (HTTP) server

http://ip_server/path

http://ip_server/path?query

This is a URL accessing a web (HTTP) server. The default port is 80. If the path refers to a directory, the web server will choose what to return; usually if there is a file named "index.html" or "index.htm" its content is returned, otherwise, a list of the files in the current directory (with appropriate links) is generated and returned. An example is <http://lwn.net>.

A query can be given in the archaic "isindex" format, consisting of a word or phrase and not including an equal sign (=). A query can also be in the longer "GET" format, which has one or more query entries of the form key=value separated by the ampersand character (&). Note that key can be repeated more than once, though it's up to the web server and its application programs to determine if there's any meaning to that. There is an unfortunate interaction with HTML/XML/SGML and the GET query format; when such URIs with more than one key are embedded in SGML/XML documents (including HTML), the ampersand (&) has to be rewritten as &. Note that not all queries use this format; larger forms may be too long to store as a URI, so they use a different interaction mechanism (called POST) which does not include the data in the URI. See the Common Gateway Interface specification at http://www.w3.org/CGI for more information.

ftp - File Transfer Protocol (FTP)

ftp://ip_server/path

This is a URL accessing a file through the file transfer protocol (FTP). The default port (for control) is 21. If no username is included, the username "anonymous" is supplied, and in that case many clients provide as the password the requestor's Internet email address. An example is <ftp://ftp.is.co.za/rfc/rfc1808.txt>.

gopher - Gopher server

gopher://ip_server/gophertype selector

gopher://ip_server/gophertype selector%09search

gopher://ip_server/gophertype selector%09search%09gopher+_string

The default gopher port is 70. gophertype is a single-character field to denote the Gopher type of the resource to which the URL refers. The entire path may also be empty, in which case the delimiting "/" is also optional and the gophertype defaults to "1".

selector is the Gopher selector string. In the Gopher protocol, Gopher selector strings are a sequence of octets which may contain any octets except 09 hexadecimal (US-ASCII HT or tab), 0A hexadecimal (US-ASCII character LF), and 0D (US-ASCII character CR).

mailto - Email address

mailto:email-address

This is an email address, usually of the form name@hostname. See mailaddr(7) for more information on the correct format of an email address. Note that any % character must be rewritten as %25. An example is <mailto:dwheeler@dwheeler.com>.

news - Newsgroup or News message

news:newsgroup-name

news:message-id

A newsgroup-name is a period-delimited hierarchical name, such as "comp.infosystems.www.misc". If <newsgroup-name> is "*" (as in <news:*>), it is used to refer to "all available news groups". An example is <news:comp.lang.ada>.

A message-id corresponds to the Message-ID of IETF RFC 1036, without the enclosing "<" and ">"; it takes the form unique@full_domain_name. A message identifier may be distinguished from a news group name by the presence of the "@" character.

telnet - Telnet login

telnet://ip_server/

The Telnet URL scheme is used to designate interactive text services that may be accessed by the Telnet protocol. The final "/" character may be omitted. The default port is 23. An example is <telnet://melvyl.ucop.edu/>.

file - Normal file

file://ip_server/path_segments

file:path_segments

This represents a file or directory accessible locally. As a special case, ip_server can be the string "localhost" or the empty string; this is interpreted as "the machine from which the URL is being interpreted". If the path is to a directory, the viewer should display the directory's contents with links to each containee; not all viewers currently do this. KDE supports generated files through the URL <file:/cgi-bin>. If the given file isn't found, browser writers may want to try to expand the filename via filename globbing (see glob(7) and glob(3)).

The second format (e.g., <file:/etc/passwd>) is a correct format for referring to a local file. However, older standards did not permit this format, and some programs don't recognize this as a URI. A more portable syntax is to use an empty string as the server name, for example, <file:///etc/passwd>; this form does the same thing and is easily recognized by pattern matchers and older programs as a URI. Note that if you really mean to say "start from the current location", don't specify the scheme at all; use a relative address like <../test.txt>, which has the side-effect of being scheme-independent. An example of this scheme is <file:///etc/passwd>.

man - Man page documentation

man:command-name

man:command-name(section)

This refers to local online manual (man) reference pages. The command name can optionally be followed by a parenthesis and section number; see man(7) for more information on the meaning of the section numbers. This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF. An example is <man:ls(1)>.

info - Info page documentation

info:virtual-filename

info:virtual-filename#nodename

info:(virtual-filename)

info:(virtual-filename)nodename

This scheme refers to online info reference pages (generated from texinfo files), a documentation format used by programs such as the GNU tools. This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF. As of this writing, GNOME and KDE differ in their URI syntax and do not accept the other's syntax. The first two formats are the GNOME format; in nodenames all spaces are written as underscores. The second two formats are the KDE format; spaces in nodenames must be written as spaces, even though this is forbidden by the URI standards. It's hoped that in the future most tools will understand all of these formats and will always accept underscores for spaces in nodenames. In both GNOME and KDE, if the form without the nodename is used the nodename is assumed to be "Top". Examples of the GNOME format are <info:gcc> and <info:gcc#G++_and_GCC>. Examples of the KDE format are <info:(gcc)> and <info:(gcc)G++ and GCC>.

whatis - Documentation search

whatis:string

This scheme searches the database of short (one-line) descriptions of commands and returns a list of descriptions containing that string. Only complete word matches are returned. See whatis(1). This URI scheme is unique to UNIX-like systems (such as Linux) and is not currently registered by the IETF.

ghelp - GNOME help documentation

ghelp:name-of-application

This loads GNOME help for the given application. Note that not much documentation currently exists in this format.

ldap - Lightweight Directory Access Protocol

ldap://hostport

ldap://hostport/

ldap://hostport/dn

ldap://hostport/dn?attributes

ldap://hostport/dn?attributes?scope

ldap://hostport/dn?attributes?scope?filter

ldap://hostport/dn?attributes?scope?filter?extensions

This scheme supports queries to the Lightweight Directory Access Protocol (LDAP), a protocol for querying a set of servers for hierarchically organized information (such as people and computing resources). See RFC 2255 for more information on the LDAP URL scheme. The components of this URL are:

hostport

the LDAP server to query, written as a hostname optionally followed by a colon and the port number. The default LDAP port is TCP port 389. If empty, the client determines which the LDAP server to use.

dn

the LDAP Distinguished Name, which identifies the base object of the LDAP search (see RFC 2253 section 3).

attributes

a comma-separated list of attributes to be returned; see RFC 2251 section 4.1.5. If omitted, all attributes should be returned.

scope

specifies the scope of the search, which can be one of "base" (for a base object search), "one" (for a one-level search), or "sub" (for a subtree search). If scope is omitted, "base" is assumed.

filter

specifies the search filter (subset of entries to return). If omitted, all entries should be returned. See RFC 2254 section 4.

extensions

a comma-separated list of type=value pairs, where the =value portion may be omitted for options not requiring it. An extension prefixed with a '!' is critical (must be supported to be valid), otherwise it is noncritical (optional).

LDAP queries are easiest to explain by example. Here's a query that asks ldap.itd.umich.edu for information about the University of Michigan in the U.S.:

```
ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US
```

To just get its postal address attribute, request:

```
ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress
```

To ask a host.com at port 6666 for information about the person with common name (cn) "Babs Jensen" at University of Michigan, request:

```
ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)
```

wais - Wide Area Information Servers

wais://hostport/database

wais://hostport/database?search

wais://hostport/database/wtype/wpath

This scheme designates a WAIS database, search, or document (see IETF RFC 1625 for more information on WAIS). Hostport is the hostname, optionally followed by a colon and port number (the default port number is 210).

The first form designates a WAIS database for searching. The second form designates a particular search of the WAIS database database. The third form designates a particular document within a WAIS database to be retrieved. wtype is the WAIS designation of the type of the object and wpath is the WAIS document-id.

other schemes

There are many other URI schemes. Most tools that accept URIs support a set of internal URIs (e.g., Mozilla has the about: scheme for internal information, and the GNOME help browser has the toc: scheme for various starting locations). There are many schemes that have been defined but are not as widely used at the current time (e.g., prospero). The nntp: scheme is deprecated in favor of the news: scheme. URNs are to be supported by the urn: scheme, with a hierarchical name space (e.g., urn:ietf:... would identify IETF documents); at this time URNs are not widely implemented. Not all tools support all schemes.

### Character encoding
URIs use a limited number of characters so that they can be typed in and used in a variety of situations.

The following characters are reserved, that is, they may appear in a URI but their use is limited to their reserved purpose (conflicting data must be escaped before forming the URI):

```
; / ? : @ & = + $ ,

```

Unreserved characters may be included in a URI. Unreserved characters include uppercase and lowercase Latin letters, decimal digits, and the following limited set of punctuation marks and symbols:

```
- _ . ! ~ * ' ( )

```

All other characters must be escaped. An escaped octet is encoded as a character triplet, consisting of the percent character "%" followed by the two hexadecimal digits representing the octet code (you can use uppercase or lowercase letters for the hexadecimal digits). For example, a blank space must be escaped as "%20", a tab character as "%09", and the "&" as "%26". Because the percent "%" character always has the reserved purpose of being the escape indicator, it must be escaped as "%25". It is common practice to escape space characters as the plus symbol (+) in query text; this practice isn't uniformly defined in the relevant RFCs (which recommend %20 instead) but any tool accepting URIs with query text should be prepared for them. A URI is always shown in its "escaped" form.

Unreserved characters can be escaped without changing the semantics of the URI, but this should not be done unless the URI is being used in a context that does not allow the unescaped character to appear. For example, "%7e" is sometimes used instead of "~" in an HTTP URL path, but the two are equivalent for an HTTP URL.

For URIs which must handle characters outside the US ASCII character set, the HTML 4.01 specification (section B.2) and IETF RFC 3986 (last paragraph of section 2.5) recommend the following approach:

(1)

translate the character sequences into UTF-8 (IETF RFC 3629)—see utf-8(7)—and then

(2)

use the URI escaping mechanism, that is, use the %HH encoding for unsafe octets.

### Writing a URI
When written, URIs should be placed inside double quotes (e.g., "http://www.kernel.org"), enclosed in angle brackets (e.g., <http://lwn.net>), or placed on a line by themselves. A warning for those who use double-quotes: never move extraneous punctuation (such as the period ending a sentence or the comma in a list) inside a URI, since this will change the value of the URI. Instead, use angle brackets instead, or switch to a quoting system that never includes extraneous characters inside quotation marks. This latter system, called the 'new' or 'logical' quoting system by "Hart's Rules" and the "Oxford Dictionary for Writers and Editors", is preferred practice in Great Britain and in various European languages. Older documents suggested inserting the prefix "URL:" just before the URI, but this form has never caught on.

The URI syntax was designed to be unambiguous. However, as URIs have become commonplace, traditional media (television, radio, newspapers, billboards, etc.) have increasingly used abbreviated URI references consisting of only the authority and path portions of the identified resource (e.g., <www.w3.org/Addressing>). Such references are primarily intended for human interpretation rather than machine, with the assumption that context-based heuristics are sufficient to complete the URI (e.g., hostnames beginning with "www" are likely to have a URI prefix of "http://" and hostnames beginning with "ftp" likely to have a prefix of "ftp://"). Many client implementations heuristically resolve these references. Such heuristics may change over time, particularly when new schemes are introduced. Since an abbreviated URI has the same syntax as a relative URL path, abbreviated URI references cannot be used where relative URIs are permitted, and can be used only when there is no defined base (such as in dialog boxes). Don't use abbreviated URIs as hypertext links inside a document; use the standard format as described here.

## STANDARDS
(IETF RFC 2396), (HTML 4.0).

## NOTES
Any tool accepting URIs (e.g., a web browser) on a Linux system should be able to handle (directly or indirectly) all of the schemes described here, including the man: and info: schemes. Handling them by invoking some other program is fine and in fact encouraged.

Technically the fragment isn't part of the URI.

For information on how to embed URIs (including URLs) in a data format, see documentation on that format. HTML uses the format <A HREF="uri"> text </A>. Texinfo files use the format @uref{uri}. Man and mdoc have the recently added UR macro, or just include the URI in the text (viewers should be able to detect :// as part of a URI).

The GNOME and KDE desktop environments currently vary in the URIs they accept, in particular in their respective help browsers. To list man pages, GNOME uses <toc:man> while KDE uses <man:(index)>, and to list info pages, GNOME uses <toc:info> while KDE uses <info:(dir)> (the author of this man page prefers the KDE approach here, though a more regular format would be even better). In general, KDE uses <file:/cgi-bin/> as a prefix to a set of generated files. KDE prefers documentation in HTML, accessed via the <file:/cgi-bin/helpindex>. GNOME prefers the ghelp scheme to store and find documentation. Neither browser handles file: references to directories at the time of this writing, making it difficult to refer to an entire directory with a browsable URI. As noted above, these environments differ in how they handle the info: scheme, probably the most important variation. It is expected that GNOME and KDE will converge to common URI formats, and a future version of this man page will describe the converged result. Efforts to aid this convergence are encouraged.

### Security
A URI does not in itself pose a security threat. There is no general guarantee that a URL, which at one time located a given resource, will continue to do so. Nor is there any guarantee that a URL will not locate a different resource at some later point in time; such a guarantee can be obtained only from the person(s) controlling that namespace and the resource in question.

It is sometimes possible to construct a URL such that an attempt to perform a seemingly harmless operation, such as the retrieval of an entity associated with the resource, will in fact cause a possibly damaging remote operation to occur. The unsafe URL is typically constructed by specifying a port number other than that reserved for the network protocol in question. The client unwittingly contacts a site that is in fact running a different protocol. The content of the URL contains instructions that, when interpreted according to this other protocol, cause an unexpected operation. An example has been the use of a gopher URL to cause an unintended or impersonating message to be sent via a SMTP server.

Caution should be used when using any URL that specifies a port number other than the default for the protocol, especially when it is a number within the reserved space.

Care should be taken when a URI contains escaped delimiters for a given protocol (for example, CR and LF characters for telnet protocols) that these are not unescaped before transmission. This might violate the protocol, but avoids the potential for such characters to be used to simulate an extra operation or parameter in that protocol, which might lead to an unexpected and possibly harmful remote operation to be performed.

It is clearly unwise to use a URI that contains a password which is intended to be secret. In particular, the use of a password within the "userinfo" component of a URI is strongly recommended against except in those rare cases where the "password" parameter is intended to be public.

## BUGS
Documentation may be placed in a variety of locations, so there currently isn't a good URI scheme for general online documentation in arbitrary formats. References of the form <file:///usr/doc/ZZZ> don't work because different distributions and local installation requirements may place the files in different directories (it may be in /usr/doc, or /usr/local/doc, or /usr/share, or somewhere else). Also, the directory ZZZ usually changes when a version changes (though filename globbing could partially overcome this). Finally, using the file: scheme doesn't easily support people who dynamically load documentation from the Internet (instead of loading the files onto a local filesystem). A future URI scheme may be added (e.g., "userdoc:") to permit programs to include cross-references to more detailed documentation without having to know the exact location of that documentation. Alternatively, a future version of the filesystem specification may specify file locations sufficiently so that the file: scheme will be able to locate documentation.

Many programs and file formats don't include a way to incorporate or implement links using URIs.

Many programs can't handle all of these different URI formats; there should be a standard mechanism to load an arbitrary URI that automatically detects the users' environment (e.g., text or graphics, desktop environment, local user preferences, and currently executing tools) and invokes the right tool for any URI.

## SEE ALSO
lynx(1), man2html(1), mailaddr(7), utf-8(7)

IETF RFC 2255


user-keyring

title: user-keyring(7)

summary: per-user keyring

text:
# user-keyring(7)

## NAME
user-keyring - per-user keyring

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

The user keyring is associated with the record that the kernel maintains for the UID. It comes into existence upon the first attempt to access either the user keyring, the user-session-keyring(7), or the session-keyring(7). The keyring remains pinned in existence so long as there are processes running with that real UID or files opened by those processes remain open. (The keyring can also be pinned indefinitely by linking it into another keyring.)

Typically, the user keyring is created by pam_keyinit(8) when a user logs in.

The user keyring is not searched by default by request_key(2). When pam_keyinit(8) creates a session keyring, it adds to it a link to the user keyring so that the user keyring will be searched when the session keyring is.

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

From the keyctl(1) utility, '@u' can be used instead of a numeric key ID in much the same way.

User keyrings are independent of clone(2), fork(2), vfork(2), execve(2), and _exit(2) excepting that the keyring is destroyed when the UID record is destroyed when the last process pinning it exits.

If it is necessary for a key associated with a user to exist beyond the UID record being garbage collected—for example, for use by a cron(8) script—then the persistent-keyring(7) should be used instead.

If a user keyring does not exist when it is accessed, it will be created.

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


user-session-keyring

title: user-session-keyring(7)

summary: per-user default session keyring

text:
# user-session-keyring(7)

## NAME
user-session-keyring - per-user default session keyring

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

The user session keyring is associated with the record that the kernel maintains for the UID. It comes into existence upon the first attempt to access either the user session keyring, the user-keyring(7), or the session-keyring(7). The keyring remains pinned in existence so long as there are processes running with that real UID or files opened by those processes remain open. (The keyring can also be pinned indefinitely by linking it into another keyring.)

The user session keyring is created on demand when a thread requests it or when a thread asks for its session-keyring(7) and that keyring doesn't exist. In the latter case, a user session keyring will be created and, if the session keyring wasn't to be created, the user session keyring will be set as the process's actual session keyring.

The user session keyring is searched by request_key(2) if the actual session keyring does not exist and is ignored otherwise.

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

From the keyctl(1) utility, '@us' can be used instead of a numeric key ID in much the same way.

User session keyrings are independent of clone(2), fork(2), vfork(2), execve(2), and _exit(2) excepting that the keyring is destroyed when the UID record is destroyed when the last process pinning it exits.

If a user session keyring does not exist when it is accessed, it will be created.

Rather than relying on the user session keyring, it is strongly recommended—especially if the process is running as root—that a session-keyring(7) be set explicitly, for example by pam_keyinit(8).

## NOTES
The user session keyring was added to support situations where a process doesn't have a session keyring, perhaps because it was created via a pathway that didn't involve PAM (e.g., perhaps it was a daemon started by inetd(8)). In such a scenario, the user session keyring acts as a substitute for the session-keyring(7).

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