UNIX(4) | Device Drivers Manual | UNIX(4) |
unix
— UNIX-domain
protocol family
#include
<sys/types.h>
#include <sys/un.h>
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.
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.
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)SOCK_SEQPACKET
or
SOCK_STREAM
socket. If enabled,
connect(2) will block until
a peer is waiting in
accept(2).LOCAL_CREDS
(int)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)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>
.
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; ...
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
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)
The sc_pid field was introduced in NetBSD 8.0.
June 28, 2022 | NetBSD 10.99 |