Updated: 2025/Nov/16
Please read Privacy Policy. It's for your privacy.
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.
NetBSD 11.99 June 28, 2022 NetBSD 11.99