diff options
Diffstat (limited to 'static/netbsd/man4/unix.4')
| -rw-r--r-- | static/netbsd/man4/unix.4 | 317 |
1 files changed, 317 insertions, 0 deletions
diff --git a/static/netbsd/man4/unix.4 b/static/netbsd/man4/unix.4 new file mode 100644 index 00000000..af2f612d --- /dev/null +++ b/static/netbsd/man4/unix.4 @@ -0,0 +1,317 @@ +.\" $NetBSD: unix.4,v 1.35 2025/03/30 00:14:12 riastradh Exp $ +.\" +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)unix.4 8.1 (Berkeley) 6/9/93 +.\" +.Dd June 28, 2022 +.Dt UNIX 4 +.Os +.Sh NAME +.Nm unix +.Nd UNIX-domain protocol family +.Sh SYNOPSIS +.In sys/types.h +.In sys/un.h +.Sh DESCRIPTION +The +.Tn UNIX Ns -domain +protocol family is a collection of protocols +that provides local (on-machine) interprocess +communication through the normal +.Xr socket 2 +mechanisms. +The +.Tn UNIX Ns -domain +family supports the +.Dv SOCK_STREAM , +.Dv SOCK_SEQPACKET , +and +.Dv SOCK_DGRAM +socket types and uses +filesystem pathnames for addressing. +.Sh ADDRESSING +.Tn UNIX Ns -domain +addresses are variable-length filesystem pathnames of +at most 104 characters. +The include file +.In sys/un.h +defines this address: +.Bd -literal -offset indent +struct sockaddr_un { + u_char sun_len; + u_char sun_family; + char sun_path[104]; +}; +.Ed +.Pp +Binding a name to a +.Tn UNIX Ns -domain +socket with +.Xr bind 2 +causes a socket file to be created in the filesystem. +This file is +.Em not +removed when the socket is closed; +.Xr unlink 2 +must be used to remove the file. +.Pp +The length of +.Tn UNIX Ns -domain +address, required by +.Xr bind 2 +and +.Xr connect 2 , +can be calculated by the macro +.Fn SUN_LEN +defined in +.In sys/un.h . +The +.Fa sun_path +field must be terminated by a NUL character to be used with +.Fn SUN_LEN , +but the terminating NUL is +.Em not +part of the address. +The +.Nx +kernel ignores any user-set value in the +.Fa sun_len +member of the structure. +.Pp +The +.Tn UNIX Ns -domain +protocol family does not support broadcast addressing or any form +of +.Dq wildcard +matching on incoming messages. +All addresses are absolute- or relative-pathnames +of other +.Tn UNIX Ns -domain +sockets. +Normal filesystem access-control mechanisms are also +applied when referencing pathnames; e.g., the destination +of a +.Xr connect 2 +or +.Xr sendto 2 +must be writable. +.Sh PROTOCOLS +The +.Tn UNIX Ns -domain +protocol family comprises simple +transport protocols that support the +.Dv SOCK_STREAM , +.Dv SOCK_SEQPACKET , +and +.Dv SOCK_DGRAM +abstractions. +.Pp +.Dv SOCK_STREAM +and +.Dv SOCK_SEQPACKET +sockets also support the communication of +.Ux +file descriptors through the use of the +.Fa msg_control +field in the +.Fa msg +argument to +.Xr sendmsg 2 +and +.Xr recvmsg 2 . +Supported file descriptors may be sent in control messages of type +.Dv SCM_RIGHTS +holding an array of +.Vt int +file descriptor objects; see +.Xr cmsg 3 +for details on assembling and examining control messages. +.Pp +A file descriptor received this way is a +.Em duplicate +of the sender's descriptor, as if it were created with a call to +.Xr dup 2 . +Per-process descriptor flags, set with +.Xr fcntl 2 , +are +.Em 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. +.Pp +A +.Ux Ns -domain +socket supports the following socket options for use with +.Xr setsockopt 2 +and +.Xr getsockopt 2 +at the level +.Dv SOL_LOCAL : +.Bl -tag -width 6n +.It Dv LOCAL_CONNWAIT Pq Vt int +May be enabled with +.Xr setsockopt 2 +on a +.Dv SOCK_SEQPACKET +or +.Dv SOCK_STREAM +socket. +If enabled, +.Xr connect 2 +will block until a peer is waiting in +.Xr accept 2 . +.It Dv LOCAL_CREDS Pq Vt int +May be enabled with +.Xr setsockopt 2 +on a +.Dv SOCK_DGRAM , +.Dv SOCK_SEQPACKET , +or a +.Dv SOCK_STREAM +socket. +This option provides a mechanism for the receiver to +receive the credentials of the process as a +.Xr recvmsg 2 +control message. +The +.Fa msg_control +field in the +.Vt msghdr +structure points +to a buffer that contains a +.Vt cmsghdr +structure followed by a variable +length +.Vt sockcred +structure, defined in +.In sys/socket.h +as follows: +.Bd -literal +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 */ +}; +.Ed +.Pp +The +.Fn SOCKCREDSIZE +macro computes the size of the +.Vt sockcred +structure for a specified number of groups. +The +.Vt cmsghdr +fields have the following values: +.Bd -literal -offset indent +cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups)) +cmsg_level = SOL_SOCKET +cmsg_type = SCM_CREDS +.Ed +.It Dv LOCAL_PEEREID Pq Vt "struct unpcbid" +May be queried with +.Xr getsockopt 2 +to get the PID and effective user and group IDs of a +.Dv SOCK_STREAM +or +.Dv SOCK_SEQPACKET +peer when it did +.Xr connect 2 +or +.Xr bind 2 . +The returned structure is +.Bd -literal +struct unpcbid { + pid_t unp_pid; /* process id */ + uid_t unp_euid; /* effective user id */ + gid_t unp_egid; /* effective group id */ +}; +.Ed +.Pp +as defined in +.In sys/un.h . +.El +.Sh EXAMPLES +The following code fragment shows how to bind a socket to pathname: +.Bd -literal -offset indent +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; +\&... +.Ed +.Sh COMPATIBILITY +The +.Fa sun_len +field exists only in system derived from +.Bx 4.4 . +On systems which don't have the +.Fn SUN_LEN +macro, the following definition is recommended: +.Bd -literal -offset indent +#ifndef SUN_LEN +#define SUN_LEN(su) sizeof(struct(sockaddr_un)) +#endif +.Ed +.Sh SEE ALSO +.Xr socket 2 , +.Xr CMSG_DATA 3 , +.Xr intro 4 +.Rs +.%T "An Introductory 4.4BSD Interprocess Communication Tutorial" +.%A Stuart Sechrest +.Re +.Pq see Pa /usr/share/doc/reference/ref3/sockets +.Rs +.%T "Advanced 4.4BSD IPC Tutorial" +.%A Samuel J. Leffler +.%A Robert S. Fabry +.%A William N. Joy +.%A Phil Lapsley +.%A Steve Miller +.%A Chris Torek +.Re +.Pq see Pa /usr/share/doc/reference/ref3/sockets-advanced +.Sh HISTORY +The +.Fa sc_pid +field was introduced in +.Nx 8.0 . |