Seth Woolley's Man Viewer

unix(7) - AF_LOCAL, AF_UNIX, PF_LOCAL, PF_UNIX, unix, AF_LOCAL, AF_UNIX, PF_LOCAL, PF_UNIX, unix - Sockets for local interprocess communication - man 7 unix

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

UNIX(7)                    Linux Programmer's Manual                   UNIX(7)



NAME
       unix,  PF_UNIX,  AF_UNIX, PF_LOCAL, AF_LOCAL - Sockets for local inter-
       process communication

SYNOPSIS
       #include <sys/socket.h>
       #include <sys/un.h>

       unix_socket = socket(2,7,n)(PF_UNIX, type, 0);
       error(8,n) = socketpair(PF_UNIX, type, 0, int *sv);


DESCRIPTION
       The PF_UNIX (also known as PF_LOCAL) socket(2,7,n) family is used to  communi-
       cate  between  processes  on the same machine efficiently. Unix sockets
       can be either anonymous (created by socketpair(2)) or associated with a
       file(1,n)  of  type socket.  Linux also supports an abstract namespace which
       is independent of the file(1,n) system.

       Valid  types  are:  SOCK_STREAM,  for  a  stream-oriented  socket(2,7,n)   and
       SOCK_DGRAM,  for  a  datagram-oriented  socket(2,7,n)  that  preserves message
       boundaries (as on most Unix implementations, Unix domain datagram sock-
       ets are always reliable and don't reorder datagrams); and (since kernel
       2.6.4) SOCK_SEQPACKET, for a connection-oriented socket(2,7,n) that  preserves
       message  boundaries  and  delivers messages in(1,8) the order that they were
       sent.

       Unix sockets support passing file(1,n) descriptors or process credentials to
       other processes using ancillary data.


ADDRESS FORMAT
       A  Unix  address  is  defined  as  a filename in(1,8) the filesystem or as a
       unique string(3,n) in(1,8) the abstract namespace.  Sockets  created  by  socket-
       pair(2) are anonymous. For non-anonymous sockets the target address can
       be set(7,n,1 builtins) using connect(2).  The local address can be set(7,n,1 builtins)  using  bind(2,n,1 builtins)(2).
       When  a socket(2,7,n) is connected and it doesn't already have a local address
       a unique address in(1,8) the abstract namespace will be generated  automati-
       cally.

              #define UNIX_PATH_MAX    108

              struct sockaddr_un {
                  sa_family_t  sun_family;              /* AF_UNIX */
                  char         sun_path[UNIX_PATH_MAX]; /* pathname */
              };

       sun_family  always contains AF_UNIX.  sun_path contains the zero-termi-
       nated pathname of the socket(2,7,n) in(1,8) the file(1,n) system.   If  sun_path  starts
       with  a zero byte it refers to the abstract namespace maintained by the
       Unix protocol module.  The socket(2,7,n)'s address in(1,8) this namespace is  given
       by  the rest of the bytes in(1,8) sun_path.  Note that names in(1,8) the abstract
       namespace are not zero-terminated.


SOCKET OPTIONS
       For historical reasons  these  socket(2,7,n)  options  are  specified  with  a
       SOL_SOCKET type even though they are PF_UNIX specific.  They can be set(7,n,1 builtins)
       with setsockopt(2) and read(2,n,1 builtins) with getsockopt(2) by specifying SOL_SOCKET
       as the socket(2,7,n) family.

       SO_PASSCRED
              Enables  the receiving of the credentials of the sending process
              ancillary message. When this option is set(7,n,1 builtins) and the socket(2,7,n) is not
              yet  connected  a  unique name in(1,8) the abstract namespace will be
              generated automatically.  Expects an integer boolean flag.


ANCILLARY MESSAGES
       Ancillary data is sent and received using  sendmsg(2)  and  recvmsg(2).
       For  historical  reasons  the  ancillary message types listed below are
       specified with a SOL_SOCKET type even though they are PF_UNIX specific.
       To  send(2,n)  them  set(7,n,1 builtins)  the  cmsg_level  field  of  the  struct cmsghdr to
       SOL_SOCKET and the cmsg_type field to the type.  For  more  information
       see cmsg(3).


       SCM_RIGHTS
              Send  or  receive  a  set(7,n,1 builtins)  of open(2,3,n) file(1,n) descriptors from another
              process.  The data portion contains an integer array of the file(1,n)
              descriptors.   The passed file(1,n) descriptors behave as though they
              have been created with dup(2).


       SCM_CREDENTIALS
              Send or receive Unix credentials.  This can be used for  authen-
              tication.   The  credentials are passed as a struct ucred ancil-
              lary message.

              struct ucred {
                  pid_t  pid;  /* process id of the sending process */
                  uid_t  uid;  /* user id of the sending process */
                  gid_t  gid;  /* group id of the sending process */
              };

       The credentials which the sender specifies are checked by  the  kernel.
       A process with effective user ID 0 is allowed to specify values that do
       not match its own.  The sender must specify its own process ID  (unless
       it has the capability CAP_SYS_ADMIN), its user ID, effective user ID or
       set(7,n,1 builtins) user ID (unless it has CAP_SETUID), and  its  group  id,  effective
       group  ID  or  set(7,n,1 builtins)  group  ID (unless it has CAP_SETGID).  To receive a
       struct ucred message the SO_PASSCRED option  must  be  enabled  on  the
       socket.


VERSIONS
       SCM_CREDENTIALS  and  the abstract namespace were introduced with Linux
       2.2 and should not be used in(1,8)  portable  programs.   (Some  BSD-derived
       systems also support credential passing, but the implementation details
       differ.)


NOTES
       In the Linux implementation, sockets which are visible in(1,8) the  filesys-
       tem  honour  the permissions of the directory they are in. Their owner,
       group and their permissions can be changed.  Creation of a  new  socket(2,7,n)
       will  fail if(3,n) the process does not have write(1,2) and search (execute) per-
       mission on the directory the socket(2,7,n) is created in.  Connecting  to  the
       socket(2,7,n)  object  requires  read(2,n,1 builtins)/write(1,2) permission.  This behavior differs
       from many BSD-derived systems which ignore permissions for  Unix  sock-
       ets. Portable programs should not rely on this feature for security.

       Binding to a socket(2,7,n) with a filename creates a socket(2,7,n) in(1,8) the file(1,n) system
       that must be deleted by the caller when it is no longer  needed  (using
       unlink(1,2)(2)).   The  usual  Unix close-behind semantics apply; the socket(2,7,n)
       can be unlinked at any time(1,2,n) and will be finally removed from  the  file(1,n)
       system when the last reference to it is closed.

       To pass file(1,n) descriptors or credentials over a SOCK_STREAM, you need to
       send(2,n)/recv  at  least  one  byte  of  non-ancillary  data  in(1,8)  the  same
       send(2,n)/recv_msg call.

       Unix  domain  stream  sockets  do not support the notion of out-of-band
       data.

ERRORS
       ENOMEM Out of memory.

       ECONNREFUSED
              connect(2) called with a socket(2,7,n)  object  that  isn't  listening.
              This  can  happen  when  the remote socket(2,7,n) does not exist or the
              filename is not a socket.

       EINVAL Invalid argument passed. A common cause is the  missing  setting
              of  AF_UNIX  in(1,8)  the  sun_type  field of passed addresses or the
              socket(2,7,n) being in(1,8) an invalid state for the applied operation.

       EOPNOTSUPP
              Stream operation called on non-stream oriented socket(2,7,n)  or  tried
              to use the out-of-band data option.

       EPROTONOSUPPORT
              Passed protocol is not PF_UNIX.

       ESOCKTNOSUPPORT
              Unknown socket(2,7,n) type.

       EPROTOTYPE
              Remote  socket(2,7,n)  does not match the local socket(2,7,n) type (SOCK_DGRAM
              vs.  SOCK_STREAM)

       EADDRINUSE
              Selected local address is already  taken  or  filesystem  socket(2,7,n)
              object already exists.

       EISCONN
              connect(2)  called  on  an  already connected socket(2,7,n) or a target
              address was specified on a connected socket.

       ENOTCONN
              Socket operation needs a target address, but the socket(2,7,n)  is  not
              connected.

       ECONNRESET
              Remote socket(2,7,n) was unexpectedly closed.

       EPIPE  Remote  socket(2,7,n) was closed on a stream socket. If enabled, a SIG-
              PIPE is sent as  well.  This  can  be  avoided  by  passing  the
              MSG_NOSIGNAL flag to sendmsg(2) or recvmsg(2).

       EFAULT User memory address was not valid.

       EPERM  The sender passed invalid credentials in(1,8) the struct ucred.

       Other  errors  can  be  generated by the generic socket(2,7,n) layer or by the
       filesystem while generating a filesystem socket(2,7,n) object. See the  appro-
       priate manual pages for more information.

SEE ALSO
       recvmsg(2),  sendmsg(2),  socket(2,7,n)(2),  socketpair(2), cmsg(3), capabili-
       ties(7), socket(2,7,n)(7)



Linux Man Page                    2004-05-27                           UNIX(7)

References for this manual (incoming links)