.\" address that can appear in the sockaddr_un structure: pathname,
.\" unnamed, and abstract.
.\"
-.TH UNIX 7 2016-07-17 "Linux" "Linux Programmer's Manual"
+.TH UNIX 7 2018-04-30 "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 ");"
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;
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
-.nf
-
+.EX
.\" #define UNIX_PATH_MAX 108
.\"
struct sockaddr_un {
sa_family_t sun_family; /* AF_UNIX */
- char sun_path[108]; /* pathname */
+ char sun_path[108]; /* Pathname */
};
-.fi
+.EE
.in
.PP
The
.I sun_family
field always contains
.BR AF_UNIX .
-On Linux
+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 accept (2))
return an argument of this type.
-
+.PP
Three types of address are distinguished in the
.I sockaddr_un
structure:
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.
an abstract socket address is distinguished (from a pathname socket)
by the fact that
.IR sun_path[0]
-is a null byte (\(aq\\0\(aq).
+is a null byte (\(aq\e0\(aq).
The socket's address in this namespace is given by the additional
bytes in
.IR sun_path
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
.\" 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
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),
.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 will fail if the process does not have write and
+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
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
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
as the socket family.
.TP
.B SO_PASSCRED
-Enables the receiving of the credentials of the sending process in an
-ancillary message.
-When this option is set and the socket is not yet connected
+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.
-Expects an integer boolean flag.
+.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).
+.\"
.SS Autobind feature
If a
.BR bind (2)
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] .
+.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.
.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
.BR send (2)
and
.BR recv (2)).
-
+.PP
The
.BR send (2)
.B MSG_MORE
flag is not supported by UNIX domain sockets.
-
-The use of
+.PP
+Before Linux 3.4,
+.\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f
+the use of
.B MSG_TRUNC
in the
.I flags
argument of
.BR recv (2)
-is not supported by UNIX domain sockets.
-
+was not supported by UNIX domain sockets.
+.PP
The
.B SO_SNDBUF
socket option does have an effect for UNIX domain sockets, but the
.BR sendmsg (2)
and
.BR recvmsg (2).
-For historical reasons the ancillary message types listed below
+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
+To send them, set the
.I cmsg_level
field of the struct
.I cmsghdr
and the
.I cmsg_type
field to the type.
-For more information see
+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.
-The passed file descriptors behave as though they have been created with
-.BR dup (2).
+.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.
Thus structure is defined in
.I <sys/socket.h>
as follows:
-
+.IP
.in +4n
-.nf
+.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 */
+ 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 */
};
-.fi
+.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 process with effective user ID 0 is allowed to specify values that do
-not match its own.
+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 ),
-its user ID, effective user ID, or saved set-user-ID (unless it has
+its real user ID, effective user ID, or saved set-user-ID (unless it has
.BR CAP_SETUID ),
-and its group ID, effective group ID, or saved set-group-ID
+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
+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 five 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)
.B SIOCINQ
For
.B SOCK_STREAM
-socket the function returns the amount of queued unread data in the receive buffer.
+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.
.\" and it may well change, probably best not to document this now.
For
.B SOCK_DGRAM
-socket,
+sockets,
the returned value is the same as
-for Internet domain datagram socket;
+for Internet domain datagram sockets;
see
.BR udp (7).
.SH ERRORS
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)
This can be avoided by passing the
.B MSG_NOSIGNAL
flag to
-.BR sendmsg (2)
+.BR send (2)
or
-.BR recvmsg (2).
+.BR sendmsg (2).
.TP
.B EPROTONOSUPPORT
Passed protocol is not
Remote socket does not match the local socket type
.RB ( SOCK_DGRAM
versus
-.BR SOCK_STREAM )
+.BR SOCK_STREAM ).
.TP
.B ESOCKTNOSUPPORT
Unknown socket type.
+.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.
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 ,
-you need
+.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
.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
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
.\" 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"
and the extra zero byte ensures that there will be
a null terminator for the string returned in
.IR sun_path :
-
-.nf
-.in +3
+.PP
+.in +4n
+.EX
void *addrp;
addrlen = sizeof(struct sockaddr_un);
if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1)
/* handle error */ ;
-printf("sun_path = %s\\n", ((struct sockaddr_un *) addrp)\->sun_path);
+printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path);
+.EE
.in
-.fi
-
+.PP
This sort of messiness can be avoided if it is guaranteed
that the applications that
.I create
Execution of the server program ends when it receives the "DOWN" command.
.SS Example output
.in +4n
-.nf
+.EX
$ \fB./server &\fP
[1] 25887
$ \fB./client 3 4\fP
Result = 0
[1]+ Done ./server
$
-.fi
+.EE
.in
.SS Program source
-.nf
+\&
+.EX
/*
* File connection.h
*/
}
result = 0;
- for(;;) {
+ for (;;) {
/* Wait for next data packet. */
sprintf(buffer, "%d", result);
ret = write(data_socket, buffer, BUFFER_SIZE);
-
if (ret == \-1) {
perror("write");
exit(EXIT_FAILURE);
ret = connect (data_socket, (const struct sockaddr *) &addr,
sizeof(struct sockaddr_un));
if (ret == \-1) {
- fprintf(stderr, "The server is down.\\n");
+ fprintf(stderr, "The server is down.\en");
exit(EXIT_FAILURE);
}
buffer[BUFFER_SIZE \- 1] = 0;
- printf("Result = %s\\n", buffer);
+ printf("Result = %s\en", buffer);
/* Close socket. */
exit(EXIT_SUCCESS);
}
-.fi
+.EE
.PP
For an example of the use of
.BR SCM_RIGHTS
projects / thirdparty / man-pages.git / blobdiff