UNIX(4)

UNIX(4) | Device Drivers Manual | UNIX(4)

# NAME

`unix` — UNIX-domain protocol family

# SYNOPSIS

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

# DESCRIPTION

The UNIX-domain protocol family is a collection of protocols that provides local (on-machine) interprocess communication through the normal socket(2) mechanisms. The UNIX-domain family supports the `SOCK_STREAM`, `SOCK_SEQPACKET`, and `SOCK_DGRAM` socket types and uses filesystem pathnames for addressing.

# ADDRESSING

UNIX-domain addresses are variable-length filesystem pathnames of at most 104 characters. The include file `<sys/un.h>` defines this address:

    struct sockaddr_un {
            u_char  sun_len;
            u_char  sun_family;
            char    sun_path[104];
    };

Binding a name to a UNIX-domain socket with bind(2) causes a socket file to be created in the filesystem. This file is not removed when the socket is closed; unlink(2) must be used to remove the file.

The length of UNIX-domain address, required by bind(2) and connect(2), can be calculated by the macro `SUN_LEN`() defined in `<sys/un.h>`. The sun_path field must be terminated by a NUL character to be used with `SUN_LEN`(), but the terminating NUL is not part of the address. The NetBSD kernel ignores any user-set value in the sun_len member of the structure.

The UNIX-domain protocol family does not support broadcast addressing or any form of “wildcard” matching on incoming messages. All addresses are absolute- or relative-pathnames of other UNIX-domain sockets. Normal filesystem access-control mechanisms are also applied when referencing pathnames; e.g., the destination of a connect(2) or sendto(2) must be writable.

# PROTOCOLS

The UNIX-domain protocol family comprises simple transport protocols that support the `SOCK_STREAM`, `SOCK_SEQPACKET`, and `SOCK_DGRAM` abstractions.

`SOCK_STREAM` and `SOCK_SEQPACKET` sockets also support the communication of UNIX file descriptors through the use of the msg_control field in the msg argument to sendmsg(2) and recvmsg(2). Supported file descriptors may be sent in control messages of type `SCM_RIGHTS` holding an array of int file descriptor objects; see cmsg(3) for details on assembling and examining control messages.

A file descriptor received this way is a duplicate of the sender's descriptor, as if it were created with a call to dup(2). Per-process descriptor flags, set with fcntl(2), are not passed to a receiver. Descriptors that are awaiting delivery, or that are purposely not received, are automatically closed by the system when the destination socket is closed.

A UNIX-domain socket supports the following socket options for use with setsockopt(2) and getsockopt(2) at the level `SOL_LOCAL`:

`LOCAL_CONNWAIT` (int)
  May be enabled with setsockopt(2) on a `SOCK_SEQPACKET` or `SOCK_STREAM` socket. If enabled, connect(2) will block until a peer is waiting in accept(2).
`LOCAL_CREDS` (int)
  May be enabled with setsockopt(2) on a `SOCK_DGRAM`, `SOCK_SEQPACKET`, or a `SOCK_STREAM` socket. This option provides a mechanism for the receiver to receive the credentials of the process as a recvmsg(2) control message. The msg_control field in the msghdr structure points to a buffer that contains a cmsghdr structure followed by a variable length sockcred structure, defined in `<sys/socket.h>` as follows:

      struct sockcred {
              pid_t   sc_pid;       /* process id */
              uid_t   sc_uid;       /* real user id */
              uid_t   sc_euid;      /* effective user id */
              gid_t   sc_gid;       /* real group id */
              gid_t   sc_egid;      /* effective group id */
              int     sc_ngroups;   /* number of supplemental groups */
              gid_t   sc_groups[1]; /* variable length */
      };

  The `SOCKCREDSIZE`() macro computes the size of the sockcred structure for a specified number of groups. The cmsghdr fields have the following values:

      cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
      cmsg_level = SOL_SOCKET
      cmsg_type = SCM_CREDS

`LOCAL_PEEREID` (struct unpcbid)
  May be queried with getsockopt(2) to get the PID and effective user and group IDs of a `SOCK_STREAM` or `SOCK_SEQPACKET` peer when it did connect(2) or bind(2). The returned structure is

      struct unpcbid {
              pid_t unp_pid;        /* process id */
              uid_t unp_euid;       /* effective user id */
              gid_t unp_egid;       /* effective group id */
      };

  as defined in `<sys/un.h>`.

# EXAMPLES

The following code fragment shows how to bind a socket to pathname:

    const char *pathname = "/path/to/socket";
    struct sockaddr_un addr;
    int ret;

    memset(&addr, 0, sizeof(addr));
    addr.sun_family = AF_LOCAL;
    if (strlen(pathname) >= sizeof(addr.sun_path))
            goto too_long;
    strncpy(addr.sun_path, pathname, sizeof(addr.sun_path));
    ret = bind(s, (const struct sockaddr *)&addr, SUN_LEN(&addr));
    if (ret != 0)
            goto bind_failed;
    ...

# COMPATIBILITY

The sun_len field exists only in system derived from 4.4BSD. On systems which don't have the `SUN_LEN`() macro, the following definition is recommended:

    #ifndef SUN_LEN
    #define SUN_LEN(su)	sizeof(struct(sockaddr_un))
    #endif

# SEE ALSO

socket(2), CMSG_DATA(3), intro(4)

Stuart Sechrest, An Introductory 4.4BSD Interprocess Communication Tutorial. (see /usr/share/doc/reference/ref3/sockets)

Samuel J. Leffler, Robert S. Fabry, William N. Joy, Phil Lapsley, Steve Miller, and Chris Torek, Advanced 4.4BSD IPC Tutorial. (see /usr/share/doc/reference/ref3/sockets-advanced)

# HISTORY

The sc_pid field was introduced in NetBSD 8.0.

June 28, 2022 | NetBSD 11.0