netbsd man page for unix

UNIX(4) 						   BSD Kernel Interfaces 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 path-
     names 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 abstrac-
     tions.  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).

     Any valid descriptor may be sent in a message.  The file descriptor(s) to be passed are described using a struct cmsghdr that is defined in
     the include file <sys/socket.h>.  The type of the message is SCM_RIGHTS, and the data portion of the messages is an array of integers repre-
     senting the file descriptors to be passed.  The number of descriptors being passed is defined by the length field of the message; the length
     field is the sum of the size of the header plus the size of the array of file descriptors.

     The received descriptor 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 two socket-level options for use with setsockopt(2) and getsockopt(2):

     The LOCAL_CREDS option may be enabled 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 {
	     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 LOCAL_PEEREID option may be used 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>.

     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

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/psd/20.ipctut)

     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/psd/21.ipc)

BSD
								   May 29, 2011 							       BSD