| .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>, |
| .\" Copyright (C) 2008-2014, Michael Kerrisk <mtk.manpages@gmail.com>, |
| .\" and Copyright (C) 2016, Heinrich Schuchardt <xypron.glpk@gmx.de> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM_ONE_PARA) |
| .\" Permission is granted to distribute possibly modified copies |
| .\" of this page provided the header is included verbatim, |
| .\" and in case of nontrivial modification author and date |
| .\" of the modification is added to the header. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified, 2003-12-02, Michael Kerrisk, <mtk.manpages@gmail.com> |
| .\" Modified, 2003-09-23, Adam Langley |
| .\" Modified, 2004-05-27, Michael Kerrisk, <mtk.manpages@gmail.com> |
| .\" Added SOCK_SEQPACKET |
| .\" 2008-05-27, mtk, Provide a clear description of the three types of |
| .\" address that can appear in the sockaddr_un structure: pathname, |
| .\" unnamed, and abstract. |
| .\" |
| .TH UNIX 7 2020-06-09 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| unix \- sockets for local interprocess communication |
| .SH SYNOPSIS |
| .B #include <sys/socket.h> |
| .br |
| .B #include <sys/un.h> |
| .PP |
| .IB unix_socket " = socket(AF_UNIX, type, 0);" |
| .br |
| .IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");" |
| .SH DESCRIPTION |
| The |
| .B AF_UNIX |
| (also known as |
| .BR AF_LOCAL ) |
| socket family is used to communicate between processes on the same machine |
| efficiently. |
| Traditionally, UNIX domain sockets can be either unnamed, |
| or bound to a filesystem pathname (marked as being of type socket). |
| Linux also supports an abstract namespace which is independent of the |
| filesystem. |
| .PP |
| Valid socket types in the UNIX domain are: |
| .BR SOCK_STREAM , |
| for a stream-oriented socket; |
| .BR SOCK_DGRAM , |
| for a datagram-oriented socket that preserves message boundaries |
| (as on most UNIX implementations, UNIX domain datagram |
| sockets are always reliable and don't reorder datagrams); |
| and (since Linux 2.6.4) |
| .BR SOCK_SEQPACKET , |
| for a sequenced-packet socket that is connection-oriented, |
| preserves message boundaries, |
| and delivers messages in the order that they were sent. |
| .PP |
| UNIX domain sockets support passing file descriptors or process credentials |
| to other processes using ancillary data. |
| .SS Address format |
| A UNIX domain socket address is represented in the following structure: |
| .PP |
| .in +4n |
| .EX |
| .\" #define UNIX_PATH_MAX 108 |
| .\" |
| struct sockaddr_un { |
| sa_family_t sun_family; /* AF_UNIX */ |
| char sun_path[108]; /* Pathname */ |
| }; |
| .EE |
| .in |
| .PP |
| The |
| .I sun_family |
| field always contains |
| .BR AF_UNIX . |
| On Linux, |
| .I sun_path |
| is 108 bytes in size; see also NOTES, below. |
| .PP |
| Various systems calls (for example, |
| .BR bind (2), |
| .BR connect (2), |
| and |
| .BR sendto (2)) |
| take a |
| .I sockaddr_un |
| argument as input. |
| Some other system calls (for example, |
| .BR getsockname (2), |
| .BR getpeername (2), |
| .BR recvfrom (2), |
| and |
| .BR accept (2)) |
| return an argument of this type. |
| .PP |
| Three types of address are distinguished in the |
| .I sockaddr_un |
| structure: |
| .IP * 3 |
| .IR pathname : |
| a UNIX domain socket can be bound to a null-terminated |
| filesystem pathname using |
| .BR bind (2). |
| When the address of a pathname socket is returned |
| (by one of the system calls noted above), |
| its length is |
| .IP |
| offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1 |
| .IP |
| and |
| .I sun_path |
| contains the null-terminated pathname. |
| (On Linux, the above |
| .BR offsetof () |
| expression equates to the same value as |
| .IR sizeof(sa_family_t) , |
| but some other implementations include other fields before |
| .IR sun_path , |
| so the |
| .BR offsetof () |
| expression more portably describes the size of the address structure.) |
| .IP |
| For further details of pathname sockets, see below. |
| .IP * |
| .IR unnamed : |
| A stream socket that has not been bound to a pathname using |
| .BR bind (2) |
| has no name. |
| Likewise, the two sockets created by |
| .BR socketpair (2) |
| are unnamed. |
| When the address of an unnamed socket is returned, |
| its length is |
| .IR "sizeof(sa_family_t)" , |
| and |
| .I sun_path |
| should not be inspected. |
| .\" There is quite some variation across implementations: FreeBSD |
| .\" says the length is 16 bytes, HP-UX 11 says it's zero bytes. |
| .IP * |
| .IR abstract : |
| an abstract socket address is distinguished (from a pathname socket) |
| by the fact that |
| .IR sun_path[0] |
| is a null byte (\(aq\e0\(aq). |
| The socket's address in this namespace is given by the additional |
| bytes in |
| .IR sun_path |
| that are covered by the specified length of the address structure. |
| (Null bytes in the name have no special significance.) |
| The name has no connection with filesystem pathnames. |
| When the address of an abstract socket is returned, |
| the returned |
| .I addrlen |
| is greater than |
| .IR "sizeof(sa_family_t)" |
| (i.e., greater than 2), and the name of the socket is contained in |
| the first |
| .IR "(addrlen \- sizeof(sa_family_t))" |
| bytes of |
| .IR sun_path . |
| .SS Pathname sockets |
| When binding a socket to a pathname, a few rules should be observed |
| for maximum portability and ease of coding: |
| .IP * 3 |
| The pathname in |
| .I sun_path |
| should be null-terminated. |
| .IP * |
| The length of the pathname, including the terminating null byte, |
| should not exceed the size of |
| .IR sun_path . |
| .IP * |
| The |
| .I addrlen |
| argument that describes the enclosing |
| .I sockaddr_un |
| structure should have a value of at least: |
| .IP |
| .nf |
| offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1 |
| .fi |
| .IP |
| or, more simply, |
| .I addrlen |
| can be specified as |
| .IR "sizeof(struct sockaddr_un)" . |
| .PP |
| There is some variation in how implementations handle UNIX domain |
| socket addresses that do not follow the above rules. |
| For example, some (but not all) implementations |
| .\" Linux does this, including for the case where the supplied path |
| .\" is 108 bytes |
| append a null terminator if none is present in the supplied |
| .IR sun_path . |
| .PP |
| When coding portable applications, |
| keep in mind that some implementations |
| .\" HP-UX |
| have |
| .I sun_path |
| as short as 92 bytes. |
| .\" Modern BSDs generally have 104, Tru64 and AIX have 104, |
| .\" Solaris and Irix have 108 |
| .PP |
| Various system calls |
| .RB ( accept (2), |
| .BR recvfrom (2), |
| .BR getsockname (2), |
| .BR getpeername (2)) |
| return socket address structures. |
| When applied to UNIX domain sockets, the value-result |
| .I addrlen |
| argument supplied to the call should be initialized as above. |
| Upon return, the argument is set to indicate the |
| .I actual |
| size of the address structure. |
| The caller should check the value returned in this argument: |
| if the output value exceeds the input value, |
| then there is no guarantee that a null terminator is present in |
| .IR sun_path . |
| (See BUGS.) |
| .\" |
| .SS Pathname socket ownership and permissions |
| In the Linux implementation, |
| pathname sockets honor the permissions of the directory they are in. |
| Creation of a new socket fails if the process does not have write and |
| search (execute) permission on the directory in which the socket is created. |
| .PP |
| On Linux, |
| connecting to a stream socket object requires write permission on that socket; |
| sending a datagram to a datagram socket likewise |
| requires write permission on that socket. |
| POSIX does not make any statement about the effect of the permissions |
| on a socket file, and on some systems (e.g., older BSDs), |
| the socket permissions are ignored. |
| Portable programs should not rely on |
| this feature for security. |
| .PP |
| When creating a new socket, the owner and group of the socket file |
| are set according to the usual rules. |
| The socket file has all permissions enabled, |
| other than those that are turned off by the process |
| .BR umask (2). |
| .PP |
| The owner, group, and permissions of a pathname socket can be changed (using |
| .BR chown (2) |
| and |
| .BR chmod (2)). |
| .\" However, fchown() and fchmod() do not seem to have an effect |
| .\" |
| .SS Abstract sockets |
| Socket permissions have no meaning for abstract sockets: |
| the process |
| .BR umask (2) |
| has no effect when binding an abstract socket, |
| and changing the ownership and permissions of the object (via |
| .BR fchown (2) |
| and |
| .BR fchmod (2)) |
| has no effect on the accessibility of the socket. |
| .PP |
| Abstract sockets automatically disappear when all open references |
| to the socket are closed. |
| .PP |
| The abstract socket namespace is a nonportable Linux extension. |
| .\" |
| .SS Socket options |
| For historical reasons, these socket options are specified with a |
| .B SOL_SOCKET |
| type even though they are |
| .B AF_UNIX |
| specific. |
| They can be set with |
| .BR setsockopt (2) |
| and read with |
| .BR getsockopt (2) |
| by specifying |
| .B SOL_SOCKET |
| as the socket family. |
| .TP |
| .B SO_PASSCRED |
| Enabling this socket option causes receipt of the credentials of |
| the sending process in an |
| .B SCM_CREDENTIALS ancillary |
| message in each subsequently received message. |
| The returned credentials are those specified by the sender using |
| .BR SCM_CREDENTIALS , |
| or a default that includes the sender's PID, real user ID, and real group ID, |
| if the sender did not specify |
| .B SCM_CREDENTIALS |
| ancillary data. |
| .IP |
| When this option is set and the socket is not yet connected, |
| a unique name in the abstract namespace will be generated automatically. |
| .IP |
| The value given as an argument to |
| .BR setsockopt (2) |
| and returned as the result of |
| .BR getsockopt (2) |
| is an integer boolean flag. |
| .TP |
| .B SO_PASSSEC |
| Enables receiving of the SELinux security label of the peer socket |
| in an ancillary message of type |
| .BR SCM_SECURITY |
| (see below). |
| .IP |
| The value given as an argument to |
| .BR setsockopt (2) |
| and returned as the result of |
| .BR getsockopt (2) |
| is an integer boolean flag. |
| .IP |
| The |
| .B SO_PASSSEC |
| option is supported for UNIX domain datagram sockets |
| .\" commit 877ce7c1b3afd69a9b1caeb1b9964c992641f52a |
| since Linux 2.6.18; |
| support for UNIX domain stream sockets was added |
| .\" commit 37a9a8df8ce9de6ea73349c9ac8bdf6ba4ec4f70 |
| in Linux 4.2. |
| .TP |
| .BR SO_PEEK_OFF |
| See |
| .BR socket (7). |
| .TP |
| .B SO_PEERCRED |
| This read-only socket option returns the |
| credentials of the peer process connected to this socket. |
| The returned credentials are those that were in effect at the time |
| of the call to |
| .BR connect (2) |
| or |
| .BR socketpair (2). |
| .IP |
| The argument to |
| .BR getsockopt (2) |
| is a pointer to a |
| .I ucred |
| structure; define the |
| .B _GNU_SOURCE |
| feature test macro to obtain the definition of that structure from |
| .IR <sys/socket.h> . |
| .IP |
| The use of this option is possible only for connected |
| .B AF_UNIX |
| stream sockets and for |
| .B AF_UNIX |
| stream and datagram socket pairs created using |
| .BR socketpair (2). |
| .TP |
| .B SO_PEERSEC |
| This read-only socket option returns the |
| security context of the peer socket connected to this socket. |
| By default, this will be the same as the security context of |
| the process that created the peer socket unless overridden |
| by the policy or by a process with the required permissions. |
| .IP |
| The argument to |
| .BR getsockopt (2) |
| is a pointer to a buffer of the specified length in bytes |
| into which the security context string will be copied. |
| If the buffer length is less than the length of the security |
| context string, then |
| .BR getsockopt (2) |
| returns \-1, sets |
| .I errno |
| to |
| .BR ERANGE , |
| and returns the required length via |
| .IR optlen . |
| The caller should allocate at least |
| .BR NAME_MAX |
| bytes for the buffer initially, although this is not guaranteed |
| to be sufficient. |
| Resizing the buffer to the returned length |
| and retrying may be necessary. |
| .IP |
| The security context string may include a terminating null character |
| in the returned length, but is not guaranteed to do so: a security |
| context "foo" might be represented as either {'f','o','o'} of length 3 |
| or {'f','o','o','\\0'} of length 4, which are considered to be |
| interchangeable. |
| The string is printable, does not contain non-terminating null characters, |
| and is in an unspecified encoding (in particular, it |
| is not guaranteed to be ASCII or UTF-8). |
| .IP |
| The use of this option for sockets in the |
| .B AF_UNIX |
| address family is supported since Linux 2.6.2 for connected stream sockets, |
| and since Linux 4.18 |
| .\" commit 0b811db2cb2aabc910e53d34ebb95a15997c33e7 |
| also for stream and datagram socket pairs created using |
| .BR socketpair (2). |
| .\" |
| .SS Autobind feature |
| If a |
| .BR bind (2) |
| call specifies |
| .I addrlen |
| as |
| .IR sizeof(sa_family_t) , |
| .\" i.e., sizeof(short) |
| or the |
| .BR SO_PASSCRED |
| socket option was specified for a socket that was |
| not explicitly bound to an address, |
| then the socket is autobound to an abstract address. |
| The address consists of a null byte |
| followed by 5 bytes in the character set |
| .IR [0\-9a\-f] . |
| Thus, there is a limit of 2^20 autobind addresses. |
| (From Linux 2.1.15, when the autobind feature was added, |
| 8 bytes were used, and the limit was thus 2^32 autobind addresses. |
| The change to 5 bytes came in Linux 2.3.15.) |
| .SS Sockets API |
| The following paragraphs describe domain-specific details and |
| unsupported features of the sockets API for UNIX domain sockets on Linux. |
| .PP |
| UNIX domain sockets do not support the transmission of |
| out-of-band data (the |
| .B MSG_OOB |
| flag for |
| .BR send (2) |
| and |
| .BR recv (2)). |
| .PP |
| The |
| .BR send (2) |
| .B MSG_MORE |
| flag is not supported by UNIX domain sockets. |
| .PP |
| Before Linux 3.4, |
| .\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f |
| the use of |
| .B MSG_TRUNC |
| in the |
| .I flags |
| argument of |
| .BR recv (2) |
| was not supported by UNIX domain sockets. |
| .PP |
| The |
| .B SO_SNDBUF |
| socket option does have an effect for UNIX domain sockets, but the |
| .B SO_RCVBUF |
| option does not. |
| For datagram sockets, the |
| .B SO_SNDBUF |
| value imposes an upper limit on the size of outgoing datagrams. |
| This limit is calculated as the doubled (see |
| .BR socket (7)) |
| option value less 32 bytes used for overhead. |
| .SS Ancillary messages |
| Ancillary data is sent and received using |
| .BR sendmsg (2) |
| and |
| .BR recvmsg (2). |
| For historical reasons, the ancillary message types listed below |
| are specified with a |
| .B SOL_SOCKET |
| type even though they are |
| .B AF_UNIX |
| specific. |
| To send them, set the |
| .I cmsg_level |
| field of the struct |
| .I cmsghdr |
| to |
| .B SOL_SOCKET |
| and the |
| .I cmsg_type |
| field to the type. |
| For more information, see |
| .BR cmsg (3). |
| .TP |
| .B SCM_RIGHTS |
| Send or receive a set of open file descriptors from another process. |
| The data portion contains an integer array of the file descriptors. |
| .IP |
| Commonly, this operation is referred to as "passing a file descriptor" |
| to another process. |
| However, more accurately, |
| what is being passed is a reference to an open file description (see |
| .BR open (2)), |
| and in the receiving process it is likely that a different |
| file descriptor number will be used. |
| Semantically, this operation is equivalent to duplicating |
| .RB ( dup (2)) |
| a file descriptor into the file descriptor table of another process. |
| .IP |
| If the buffer used to receive the ancillary data containing |
| file descriptors is too small (or is absent), |
| then the ancillary data is truncated (or discarded) |
| and the excess file descriptors are automatically closed |
| in the receiving process. |
| .IP |
| If the number of file descriptors received in the ancillary data would |
| cause the process to exceed its |
| .B RLIMIT_NOFILE |
| resource limit (see |
| .BR getrlimit (2)), |
| the excess file descriptors are automatically closed |
| in the receiving process. |
| .IP |
| The kernel constant |
| .BR SCM_MAX_FD |
| defines a limit on the number of file descriptors in the array. |
| Attempting to send an array larger than this limit causes |
| .BR sendmsg (2) |
| to fail with the error |
| .BR EINVAL . |
| .BR SCM_MAX_FD |
| has the value 253 |
| (or 255 in kernels |
| .\" commit bba14de98753cb6599a2dae0e520714b2153522d |
| before 2.6.38). |
| .TP |
| .B SCM_CREDENTIALS |
| Send or receive UNIX credentials. |
| This can be used for authentication. |
| The credentials are passed as a |
| .I struct ucred |
| ancillary message. |
| This structure is defined in |
| .I <sys/socket.h> |
| as follows: |
| .IP |
| .in +4n |
| .EX |
| 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 */ |
| }; |
| .EE |
| .in |
| .IP |
| Since glibc 2.8, the |
| .B _GNU_SOURCE |
| feature test macro must be defined (before including |
| .I any |
| header files) in order to obtain the definition |
| of this structure. |
| .IP |
| The credentials which the sender specifies are checked by the kernel. |
| A privileged process is allowed to specify values that do not match its own. |
| The sender must specify its own process ID (unless it has the capability |
| .BR CAP_SYS_ADMIN , |
| in which case the PID of any existing process may be specified), |
| its real user ID, effective user ID, or saved set-user-ID (unless it has |
| .BR CAP_SETUID ), |
| and its real group ID, effective group ID, or saved set-group-ID |
| (unless it has |
| .BR CAP_SETGID ). |
| .IP |
| To receive a |
| .I struct ucred |
| message, the |
| .B SO_PASSCRED |
| option must be enabled on the socket. |
| .TP |
| .B SCM_SECURITY |
| Receive the SELinux security context (the security label) |
| of the peer socket. |
| The received ancillary data is a null-terminated string containing |
| the security context. |
| The receiver should allocate at least |
| .BR NAME_MAX |
| bytes in the data portion of the ancillary message for this data. |
| .IP |
| To receive the security context, the |
| .B SO_PASSSEC |
| option must be enabled on the socket (see above). |
| .PP |
| When sending ancillary data with |
| .BR sendmsg (2), |
| only one item of each of the above types may be included in the sent message. |
| .PP |
| At least one byte of real data should be sent when sending ancillary data. |
| On Linux, this is required to successfully send ancillary data over |
| a UNIX domain stream socket. |
| When sending ancillary data over a UNIX domain datagram socket, |
| it is not necessary on Linux to send any accompanying real data. |
| However, portable applications should also include at least one byte |
| of real data when sending ancillary data over a datagram socket. |
| .PP |
| When receiving from a stream socket, |
| ancillary data forms a kind of barrier for the received data. |
| For example, suppose that the sender transmits as follows: |
| .PP |
| .RS |
| .PD 0 |
| .IP 1. 3 |
| .BR sendmsg (2) |
| of four bytes, with no ancillary data. |
| .IP 2. |
| .BR sendmsg (2) |
| of one byte, with ancillary data. |
| .IP 3. |
| .BR sendmsg (2) |
| of four bytes, with no ancillary data. |
| .PD |
| .RE |
| .PP |
| Suppose that the receiver now performs |
| .BR recvmsg (2) |
| calls each with a buffer size of 20 bytes. |
| The first call will receive five bytes of data, |
| along with the ancillary data sent by the second |
| .BR sendmsg (2) |
| call. |
| The next call will receive the remaining four bytes of data. |
| .PP |
| If the space allocated for receiving incoming ancillary data is too small |
| then the ancillary data is truncated to the number of headers |
| that will fit in the supplied buffer (or, in the case of an |
| .BR SCM_RIGHTS |
| file descriptor list, the list of file descriptors may be truncated). |
| If no buffer is provided for incoming ancillary data (i.e., the |
| .I msg_control |
| field of the |
| .I msghdr |
| structure supplied to |
| .BR recvmsg (2) |
| is NULL), |
| then the incoming ancillary data is discarded. |
| In both of these cases, the |
| .BR MSG_CTRUNC |
| flag will be set in the |
| .I msg.msg_flags |
| value returned by |
| .BR recvmsg (2). |
| .\" |
| .SS Ioctls |
| The following |
| .BR ioctl (2) |
| calls return information in |
| .IR value . |
| The correct syntax is: |
| .PP |
| .RS |
| .nf |
| .BI int " value"; |
| .IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");" |
| .fi |
| .RE |
| .PP |
| .I ioctl_type |
| can be: |
| .TP |
| .B SIOCINQ |
| For |
| .B SOCK_STREAM |
| sockets, this call returns the number of unread bytes in the receive buffer. |
| The socket must not be in LISTEN state, otherwise an error |
| .RB ( EINVAL ) |
| is returned. |
| .B SIOCINQ |
| is defined in |
| .IR <linux/sockios.h> . |
| .\" FIXME . http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002, |
| .\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers |
| Alternatively, |
| you can use the synonymous |
| .BR FIONREAD , |
| defined in |
| .IR <sys/ioctl.h> . |
| .\" SIOCOUTQ also has an effect for UNIX domain sockets, but not |
| .\" quite what userland might expect. It seems to return the number |
| .\" of bytes allocated for buffers containing pending output. |
| .\" That number is normally larger than the number of bytes of pending |
| .\" output. Since this info is, from userland's point of view, imprecise, |
| .\" and it may well change, probably best not to document this now. |
| For |
| .B SOCK_DGRAM |
| sockets, |
| the returned value is the same as |
| for Internet domain datagram sockets; |
| see |
| .BR udp (7). |
| .SH ERRORS |
| .TP |
| .B EADDRINUSE |
| The specified local address is already in use or the filesystem socket |
| object already exists. |
| .TP |
| .B EBADF |
| This error can occur for |
| .BR sendmsg (2) |
| when sending a file descriptor as ancillary data over |
| a UNIX domain socket (see the description of |
| .BR SCM_RIGHTS , |
| above), and indicates that the file descriptor number that |
| is being sent is not valid (e.g., it is not an open file descriptor). |
| .TP |
| .B ECONNREFUSED |
| The remote address specified by |
| .BR connect (2) |
| was not a listening socket. |
| This error can also occur if the target pathname is not a socket. |
| .TP |
| .B ECONNRESET |
| Remote socket was unexpectedly closed. |
| .TP |
| .B EFAULT |
| User memory address was not valid. |
| .TP |
| .B EINVAL |
| Invalid argument passed. |
| A common cause is that the value |
| .B AF_UNIX |
| was not specified in the |
| .I sun_type |
| field of passed addresses, or the socket was in an |
| invalid state for the applied operation. |
| .TP |
| .B EISCONN |
| .BR connect (2) |
| called on an already connected socket or a target address was |
| specified on a connected socket. |
| .TP |
| .B ENOENT |
| The pathname in the remote address specified to |
| .BR connect (2) |
| did not exist. |
| .TP |
| .B ENOMEM |
| Out of memory. |
| .TP |
| .B ENOTCONN |
| Socket operation needs a target address, but the socket is not connected. |
| .TP |
| .B EOPNOTSUPP |
| Stream operation called on non-stream oriented socket or tried to |
| use the out-of-band data option. |
| .TP |
| .B EPERM |
| The sender passed invalid credentials in the |
| .IR "struct ucred" . |
| .TP |
| .B EPIPE |
| Remote socket was closed on a stream socket. |
| If enabled, a |
| .B SIGPIPE |
| is sent as well. |
| This can be avoided by passing the |
| .B MSG_NOSIGNAL |
| flag to |
| .BR send (2) |
| or |
| .BR sendmsg (2). |
| .TP |
| .B EPROTONOSUPPORT |
| Passed protocol is not |
| .BR AF_UNIX . |
| .TP |
| .B EPROTOTYPE |
| Remote socket does not match the local socket type |
| .RB ( SOCK_DGRAM |
| versus |
| .BR SOCK_STREAM ). |
| .TP |
| .B ESOCKTNOSUPPORT |
| Unknown socket type. |
| .TP |
| .B ESRCH |
| While sending an ancillary message containing credentials |
| .RB ( SCM_CREDENTIALS ), |
| the caller specified a PID that does not match any existing process. |
| .TP |
| .B ETOOMANYREFS |
| This error can occur for |
| .BR sendmsg (2) |
| when sending a file descriptor as ancillary data over |
| a UNIX domain socket (see the description of |
| .BR SCM_RIGHTS , |
| above). |
| It occurs if the number of "in-flight" file descriptors exceeds the |
| .B RLIMIT_NOFILE |
| resource limit and the caller does not have the |
| .BR CAP_SYS_RESOURCE |
| capability. |
| An in-flight file descriptor is one that has been sent using |
| .BR sendmsg (2) |
| but has not yet been accepted in the recipient process using |
| .BR recvmsg (2). |
| .IP |
| This error is diagnosed since mainline Linux 4.5 |
| (and in some earlier kernel versions where the fix has been backported). |
| .\" commit 712f4aad406bb1ed67f3f98d04c044191f0ff593 |
| In earlier kernel versions, |
| it was possible to place an unlimited number of file descriptors in flight, |
| by sending each file descriptor with |
| .BR sendmsg (2) |
| and then closing the file descriptor so that it was not accounted against the |
| .B RLIMIT_NOFILE |
| resource limit. |
| .PP |
| 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 information. |
| .SH VERSIONS |
| .B SCM_CREDENTIALS |
| and the abstract namespace were introduced with Linux 2.2 and should not |
| be used in portable programs. |
| (Some BSD-derived systems also support credential passing, |
| but the implementation details differ.) |
| .SH NOTES |
| Binding to a socket with a filename creates a socket |
| in the filesystem that must be deleted by the caller when it is no |
| longer needed (using |
| .BR unlink (2)). |
| The usual UNIX close-behind semantics apply; the socket can be unlinked |
| at any time and will be finally removed from the filesystem when the last |
| reference to it is closed. |
| .PP |
| To pass file descriptors or credentials over a |
| .BR SOCK_STREAM |
| socket, you must |
| to send or receive at least one byte of nonancillary data in the same |
| .BR sendmsg (2) |
| or |
| .BR recvmsg (2) |
| call. |
| .PP |
| UNIX domain stream sockets do not support the notion of out-of-band data. |
| .\" |
| .SH BUGS |
| When binding a socket to an address, |
| Linux is one of the implementations that appends a null terminator |
| if none is supplied in |
| .IR sun_path . |
| In most cases this is unproblematic: |
| when the socket address is retrieved, |
| it will be one byte longer than that supplied when the socket was bound. |
| However, there is one case where confusing behavior can result: |
| if 108 non-null bytes are supplied when a socket is bound, |
| then the addition of the null terminator takes the length of |
| the pathname beyond |
| .IR sizeof(sun_path) . |
| Consequently, when retrieving the socket address |
| (for example, via |
| .BR accept (2)), |
| .\" The behavior on Solaris is quite similar. |
| if the input |
| .I addrlen |
| argument for the retrieving call is specified as |
| .IR "sizeof(struct sockaddr_un)" , |
| then the returned address structure |
| .I won't |
| have a null terminator in |
| .IR sun_path . |
| .PP |
| In addition, some implementations |
| .\" i.e., traditional BSD |
| don't require a null terminator when binding a socket (the |
| .I addrlen |
| argument is used to determine the length of |
| .IR sun_path ) |
| and when the socket address is retrieved on these implementations, |
| there is no null terminator in |
| .IR sun_path . |
| .PP |
| Applications that retrieve socket addresses can (portably) code |
| to handle the possibility that there is no null terminator in |
| .IR sun_path |
| by respecting the fact that the number of valid bytes in the pathname is: |
| .PP |
| strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) |
| .\" The following patch to amend kernel behavior was rejected: |
| .\" http://thread.gmane.org/gmane.linux.kernel.api/2437 |
| .\" Subject: [patch] Fix handling of overlength pathname in AF_UNIX sun_path |
| .\" 2012-04-17 |
| .\" And there was a related discussion in the Austin list: |
| .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/5735 |
| .\" Subject: Having a sun_path with no null terminator |
| .\" 2012-04-18 |
| .\" |
| .\" FIXME . Track http://austingroupbugs.net/view.php?id=561 |
| .PP |
| Alternatively, an application can retrieve |
| the socket address by allocating a buffer of size |
| .I "sizeof(struct sockaddr_un)+1" |
| that is zeroed out before the retrieval. |
| The retrieving call can specify |
| .I addrlen |
| as |
| .IR "sizeof(struct sockaddr_un)" , |
| and the extra zero byte ensures that there will be |
| a null terminator for the string returned in |
| .IR sun_path : |
| .PP |
| .in +4n |
| .EX |
| void *addrp; |
| |
| addrlen = sizeof(struct sockaddr_un); |
| addrp = malloc(addrlen + 1); |
| if (addrp == NULL) |
| /* Handle error */ ; |
| memset(addrp, 0, addrlen + 1); |
| |
| if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1) |
| /* handle error */ ; |
| |
| printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path); |
| .EE |
| .in |
| .PP |
| This sort of messiness can be avoided if it is guaranteed |
| that the applications that |
| .I create |
| pathname sockets follow the rules outlined above under |
| .IR "Pathname sockets" . |
| .SH EXAMPLES |
| The following code demonstrates the use of sequenced-packet |
| sockets for local interprocess communication. |
| It consists of two programs. |
| The server program waits for a connection from the client program. |
| The client sends each of its command-line arguments in separate messages. |
| The server treats the incoming messages as integers and adds them up. |
| The client sends the command string "END". |
| The server sends back a message containing the sum of the client's integers. |
| The client prints the sum and exits. |
| The server waits for the next client to connect. |
| To stop the server, the client is called with the command-line argument "DOWN". |
| .PP |
| The following output was recorded while running the server in the background |
| and repeatedly executing the client. |
| Execution of the server program ends when it receives the "DOWN" command. |
| .SS Example output |
| .in +4n |
| .EX |
| $ \fB./server &\fP |
| [1] 25887 |
| $ \fB./client 3 4\fP |
| Result = 7 |
| $ \fB./client 11 \-5\fP |
| Result = 6 |
| $ \fB./client DOWN\fP |
| Result = 0 |
| [1]+ Done ./server |
| $ |
| .EE |
| .in |
| .SS Program source |
| \& |
| .EX |
| /* |
| * File connection.h |
| */ |
| |
| #define SOCKET_NAME "/tmp/9Lq7BNBnBycd6nxy.socket" |
| #define BUFFER_SIZE 12 |
| |
| /* |
| * File server.c |
| */ |
| |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <string.h> |
| #include <sys/socket.h> |
| #include <sys/un.h> |
| #include <unistd.h> |
| #include "connection.h" |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| struct sockaddr_un name; |
| int down_flag = 0; |
| int ret; |
| int connection_socket; |
| int data_socket; |
| int result; |
| char buffer[BUFFER_SIZE]; |
| |
| /* Create local socket. */ |
| |
| connection_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0); |
| if (connection_socket == \-1) { |
| perror("socket"); |
| exit(EXIT_FAILURE); |
| } |
| |
| /* |
| * For portability clear the whole structure, since some |
| * implementations have additional (nonstandard) fields in |
| * the structure. |
| */ |
| |
| memset(&name, 0, sizeof(name)); |
| |
| /* Bind socket to socket name. */ |
| |
| name.sun_family = AF_UNIX; |
| strncpy(name.sun_path, SOCKET_NAME, sizeof(name.sun_path) \- 1); |
| |
| ret = bind(connection_socket, (const struct sockaddr *) &name, |
| sizeof(name)); |
| if (ret == \-1) { |
| perror("bind"); |
| exit(EXIT_FAILURE); |
| } |
| |
| /* |
| * Prepare for accepting connections. The backlog size is set |
| * to 20. So while one request is being processed other requests |
| * can be waiting. |
| */ |
| |
| ret = listen(connection_socket, 20); |
| if (ret == \-1) { |
| perror("listen"); |
| exit(EXIT_FAILURE); |
| } |
| |
| /* This is the main loop for handling connections. */ |
| |
| for (;;) { |
| |
| /* Wait for incoming connection. */ |
| |
| data_socket = accept(connection_socket, NULL, NULL); |
| if (data_socket == \-1) { |
| perror("accept"); |
| exit(EXIT_FAILURE); |
| } |
| |
| result = 0; |
| for (;;) { |
| |
| /* Wait for next data packet. */ |
| |
| ret = read(data_socket, buffer, sizeof(buffer)); |
| if (ret == \-1) { |
| perror("read"); |
| exit(EXIT_FAILURE); |
| } |
| |
| /* Ensure buffer is 0\-terminated. */ |
| |
| buffer[sizeof(buffer) \- 1] = 0; |
| |
| /* Handle commands. */ |
| |
| if (!strncmp(buffer, "DOWN", sizeof(buffer))) { |
| down_flag = 1; |
| break; |
| } |
| |
| if (!strncmp(buffer, "END", sizeof(buffer))) { |
| break; |
| } |
| |
| /* Add received summand. */ |
| |
| result += atoi(buffer); |
| } |
| |
| /* Send result. */ |
| |
| sprintf(buffer, "%d", result); |
| ret = write(data_socket, buffer, sizeof(buffer)); |
| if (ret == \-1) { |
| perror("write"); |
| exit(EXIT_FAILURE); |
| } |
| |
| /* Close socket. */ |
| |
| close(data_socket); |
| |
| /* Quit on DOWN command. */ |
| |
| if (down_flag) { |
| break; |
| } |
| } |
| |
| close(connection_socket); |
| |
| /* Unlink the socket. */ |
| |
| unlink(SOCKET_NAME); |
| |
| exit(EXIT_SUCCESS); |
| } |
| |
| /* |
| * File client.c |
| */ |
| |
| #include <errno.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <string.h> |
| #include <sys/socket.h> |
| #include <sys/un.h> |
| #include <unistd.h> |
| #include "connection.h" |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| struct sockaddr_un addr; |
| int ret; |
| int data_socket; |
| char buffer[BUFFER_SIZE]; |
| |
| /* Create local socket. */ |
| |
| data_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0); |
| if (data_socket == \-1) { |
| perror("socket"); |
| exit(EXIT_FAILURE); |
| } |
| |
| /* |
| * For portability clear the whole structure, since some |
| * implementations have additional (nonstandard) fields in |
| * the structure. |
| */ |
| |
| memset(&addr, 0, sizeof(addr)); |
| |
| /* Connect socket to socket address */ |
| |
| addr.sun_family = AF_UNIX; |
| strncpy(addr.sun_path, SOCKET_NAME, sizeof(addr.sun_path) \- 1); |
| |
| ret = connect(data_socket, (const struct sockaddr *) &addr, |
| sizeof(addr)); |
| if (ret == \-1) { |
| fprintf(stderr, "The server is down.\en"); |
| exit(EXIT_FAILURE); |
| } |
| |
| /* Send arguments. */ |
| |
| for (int i = 1; i < argc; ++i) { |
| ret = write(data_socket, argv[i], strlen(argv[i]) + 1); |
| if (ret == \-1) { |
| perror("write"); |
| break; |
| } |
| } |
| |
| /* Request result. */ |
| |
| strcpy(buffer, "END"); |
| ret = write(data_socket, buffer, strlen(buffer) + 1); |
| if (ret == \-1) { |
| perror("write"); |
| exit(EXIT_FAILURE); |
| } |
| |
| /* Receive result. */ |
| |
| ret = read(data_socket, buffer, sizeof(buffer)); |
| if (ret == \-1) { |
| perror("read"); |
| exit(EXIT_FAILURE); |
| } |
| |
| /* Ensure buffer is 0\-terminated. */ |
| |
| buffer[sizeof(buffer) \- 1] = 0; |
| |
| printf("Result = %s\en", buffer); |
| |
| /* Close socket. */ |
| |
| close(data_socket); |
| |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .PP |
| For examples of the use of |
| .BR SCM_RIGHTS , |
| see |
| .BR cmsg (3) |
| and |
| .BR seccomp_user_notif (2). |
| .SH SEE ALSO |
| .BR recvmsg (2), |
| .BR sendmsg (2), |
| .BR socket (2), |
| .BR socketpair (2), |
| .BR cmsg (3), |
| .BR capabilities (7), |
| .BR credentials (7), |
| .BR socket (7), |
| .BR udp (7) |