diff options
Diffstat (limited to 'man7/unix.7')
| -rw-r--r-- | man7/unix.7 | 1210 |
1 files changed, 0 insertions, 1210 deletions
diff --git a/man7/unix.7 b/man7/unix.7 deleted file mode 100644 index b9e28b20e..000000000 --- a/man7/unix.7 +++ /dev/null @@ -1,1210 +0,0 @@ -.\" 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 (date) "Linux man-pages (unreleased)" -.SH NAME -unix \- sockets for local interprocess communication -.SH SYNOPSIS -.nf -.B #include <sys/socket.h> -.B #include <sys/un.h> -.PP -.IB unix_socket " = socket(AF_UNIX, type, 0);" -.IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");" -.fi -.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 BUGS, 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: -.TP -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 -.in +4n -.EX -offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1 -.EE -.in -.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. -.TP -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. -.TP -abstract -an abstract socket address is distinguished (from a pathname socket) -by the fact that -.I sun_path[0] -is a null byte (\[aq]\e0\[aq]). -The socket's address in this namespace is given by the additional -bytes in -.I 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 -.I sizeof(sa_family_t) -(i.e., greater than 2), and the name of the socket is contained in -the first -.I (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 \[bu] 3 -The pathname in -.I sun_path -should be null-terminated. -.IP \[bu] -The length of the pathname, including the terminating null byte, -should not exceed the size of -.IR sun_path . -.IP \[bu] -The -.I addrlen -argument that describes the enclosing -.I sockaddr_un -structure should have a value of at least: -.IP -.in +4n -.EX -offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1 -.EE -.in -.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 -.B 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 -.B 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 -.B 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 -.B 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\[ha]20 autobind addresses. -(From Linux 2.1.15, when the autobind feature was added, -8 bytes were used, and the limit was thus 2\[ha]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 -.B 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 . -.B SCM_MAX_FD -has the value 253 -.\" commit bba14de98753cb6599a2dae0e520714b2153522d -(or 255 before Linux 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 -.B 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) 5 -.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 -.B 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 -.B 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 . https://www.sourceware.org/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 ENFILE -The system-wide limit on the total number of open files has been reached. -.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 -.B 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 -.B SOCK_STREAM -socket, you must -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 -.I sun_path -by respecting the fact that the number of valid bytes in the pathname is: -.PP -.in +4n -.EX -strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) -.EE -.in -.\" 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 (size_t 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_unotify (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) |