home | help 
UNIX(4) 		     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 and SOCK_DGRAM
     socket types and uses file system pathnames for addressing.

ADDRESSING
     Unix-domain  addresses are variable-length file system 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 file system.  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  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 file
     system access-control mechanisms are also applied	when  referencing  path-
     names; e.g., the destination of a connect(2) or sendto(2) must be writable.

PROTOCOLS
     The  Unix-domain protocol family is comprised of simple transport protocols
     that support the  SOCK_STREAM  and  SOCK_DGRAM  abstractions.   SOCK_STREAM
     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 in-
     clude file <sys/socket.h>.  The type of the message is SCM_RIGHTS, and  the
     data  portion of the messages is an array of integers representing the file
     descriptors to be passed.	The number of descriptors being  passed  is  de-
     fined  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  de-
     livery, or that are purposely not received, are automatically closed by the
     system when the destination socket is closed.

     The effective credentials (i.e., the user ID and group list) of a peer on a
     SOCK_STREAM  socket may be obtained using the LOCAL_PEERCRED socket option.
     This may be used by a server to obtain and verify the  credentials  of  its
     client,  and  vice  versa	by  the  client to verify the credentials of the
     server.  These will arrive in the form of a filled in  struct  xucred  (de-
     fined in <sys/ucred.h>).  The credentials presented to the server (the lis-
     ten(2)  caller) are those of the client when it called connect(2); the cre-
     dentials presented to the client (the connect(2) caller) are those  of  the
     server  when  it called listen(2).  This mechanism is reliable; there is no
     way for either party to influence the credentials presented to its peer ex-
     cept by calling the appropriate system call (e.g., connect(2) or listen(2))
     under different effective credentials.

     UNIX domain sockets support a number of socket options  which  can  be  set
     with setsockopt(2) and tested with getsockopt(2):

     LOCAL_CREDS     This option may be enabled on a SOCK_DGRAM 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 struc-
		     ture followed by a variable length sockcred structure,  de-
		     fined 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  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_CONNWAIT  Used  with SOCK_STREAM sockets, this option causes the con-
		     nect(2) function to block until accept(2) has  been  called
		     on the listening socket.

SEE ALSO
     socket(2), intro(4)

     "An Introductory 4.3 BSD Interprocess Communication Tutorial", PS1, 7.

     "An Advanced 4.3 BSD Interprocess Communication Tutorial", PS1, 8.

FreeBSD 7.2			  July 15, 2001 			 UNIX(4)
home | help