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

NAME
       unix,  PF_UNIX,  AF_UNIX, PF_LOCAL, AF_LOCAL - Sockets for
       local interprocess communication.

SYNOPSIS
       #include <sys/socket.h>
       #include <sys/un.h>
       unix_socket = socket(PF_UNIX, type, 0);
       error = socketpair(PF_UNIX, type, 0, int *sv);

DESCRIPTION
       The PF_UNIX (also called PF_LOCAL) socket family  is  used
       to communicate between processes on the same machine effi-
       ciently. Unix sockets can be either anonymous (created  by
       socketpair(2) ) or associated with an socket object in the
       filesystem namespace (and subject to the usual  filesystem
       permission  checks).   Since  Linux  2.2  an abstract name
       space independent from the file system is supported too.

       Valid types are SOCK_STREAM for a stream  oriented  socket
       type  and  SOCK_DGRAM  for a datagram oriented socket type
       that preserves message boundaries. Unix sockets are always
       reliable.

       Unix  sockets  support passing file descriptors or process
       credentials to other processes using ancillary data.

ADDRESS FORMAT
       A unix address is defined as a unique string either in the
       filesystem or in the abstract namespace. Sockets create by
       socketpair(2) don't have an address. For other sockets the
       target  address  can  be  set using connect(2).  The local
       address can be set using bind(2).  When a socket  is  con-
       nected  and  it  doesn't  have  a  local address already a
       unique address in the abstract namespace will be generated
       automatically.

              #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 (or AF_LOCAL which is a
       synonym) sun_path contains the null terminated pathname of
       the filesystem socket object.  If sun_path starts with a 0
       byte it refers to the abstract namespace maintained by the
       Unix  protocol  module.  After  that a non-zero terminated
       byte sequence of the passed length number  of  bytes  -  1
       follows.

SOCKET OPTIONS
       For  historical reasons these socket options are specified
       with a SOL_SOCKET type. They are PF_UNIX specific  though.
       They  can be set with setsockopt(2) and read with getsock-
       opt(2) by specifying SOL_SOCKET as the socket family.

       SO_PASSCRED enables the receiving of  the  credentials  of
       the sending process ancillary message. When this option is
       set and the socket is not connected yet an unique name  in
       the  abstract  namespace  will be generated automatically.
       Expects an integer boolean flag.

ANCILLARY MESSAGES
       For historical reasons these ancillary  message  type  are
       specified  with  a  SOL_SOCKET type. They are PF_UNIX spe-
       cific though. To send them set 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 file  descriptor.   The  data
       portion  contains a integer array of the file descriptors.

       SCM_CREDENTIALS Send or receive  the  credentials  of  the
       sending  process. This can be used for authentication. The
       credentials are passed as a struct  ucred  ancillary  mes-
       sage.

              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 */
              };

       During  sending  only  root  processes are allowed specify
       credentials they don't own.  On receiving the current cre-
       dentials  of  the  sending  process are passed, unless the
       user specified different credentials (and had  the  rights
       to  do  that).   To  receive  the  message the SO_PASSCRED
       option must be enabled.

VERSIONS
       SCM_CREDENTIALS and the abstract namespace were introduced
       with Linux 2.2.

NOTES
       In  Linux  PF_UNIX sockets visible in the filesystem honor
       the permissions of the the directory they are part of.  It
       is also possible to change their owner, groups and permis-
       sions. To create a new socket (bind) write and  executable
       permission  to  the  directory  containing  the  socket is
       needed,  for  connecting  read/write  permissions  to  the
       socket  object  in  the filesystem.  This behavior differs
       from many BSD derived systems which ignore permissions for
       Unix  sockets.  Portable  programs should not rely on this
       feature.

       To pass  file  descriptors  or  credentials  you  need  to
       send/read at least one byte.

ERRORS
       ENOMEM Out of memory.

       ECONNREFUSED
              connect(2)  called  with a socket object that isn't
              listening. This can happen when the  remote  socket
              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 the sun_type field of
              passed  addresses or the socket being in an invalid
              state for the applied operation.

       EOPNOTSUPP
              Stream  operation  called  on  non-stream  oriented
              socket or tried to use the out-of-band data option.

       EPROTONOSUPPORT
              Passed protocol is not PF_UNIX.

       ESOCKTNOSUPPORT
              Unknown socket type.

       EPROTOTYPE
              Remote socket does not match the local socket  type
              (SOCK_DGRAM vs.  SOCK_STREAM)

       EADDRINUSE
              Selected local address is already taken or filesys-
              tem socket object already exists.

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

       ENOTCONN
              Socket operation needs a target  address,  but  the
              socket is not connected.

       ECONNRESET
              Remote socket was unexpectedly closed.

       EPIPE  Remote  socket  was  closed  on a stream socket. If
              enabled, a SIGPIPE 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.

       Other errors can be generated by the generic socket  layer
       or  by the filesystem while generating a filesystem socket
       object. See the appropriate manual pages for more informa-
       tion.

SEE ALSO
       socket(4),    sendmsg(2),    recvmsg(2),    socketpair(2),
       socket(2)

Linux Man Page              3 Oct 1998                          1