diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2008-08-08 16:41:48 +0000 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2008-08-08 16:41:48 +0000 |
| commit | 77117f4fc55addbb657d1c87e2f86911d7e432c9 (patch) | |
| tree | 5a1c4291dea39575e350a55242d246c04b25e821 /man7/unix.7 | |
| parent | 10874173dba2edf045eebd9e85945970182dbaf6 (diff) | |
| download | man-pages-77117f4fc55addbb657d1c87e2f86911d7e432c9.tar.gz | |
Reverting blunder in commit 4699
Diffstat (limited to 'man7/unix.7')
| -rw-r--r-- | man7/unix.7 | 367 |
1 files changed, 359 insertions, 8 deletions
diff --git a/man7/unix.7 b/man7/unix.7 index 631a99c5a8..3f66b37427 100644 --- a/man7/unix.7 +++ b/man7/unix.7 @@ -1,8 +1,359 @@ -.TH UNIX 7 2008-08-07 "Linux" "Linux Programmer's Manual" -.TH UNIX 7 2008-08-07 "Linux" "Linux Programmer's Manual" -.TH UNIX 7 2008-08-07 "Linux" "Linux Programmer's Manual" -.TH UNIX 7 2008-08-07 "Linux" "Linux Programmer's Manual" -.TH UNIX 7 2008-08-07 "Linux" "Linux Programmer's Manual" -.TH UNIX 7 2008-08-07 "Linux" "Linux Programmer's Manual" -.TH UNIX 7 2008-08-07 "Linux" "Linux Programmer's Manual" -.TH UNIX 7 2008-08-07 "Linux" "Linux Programmer's Manual" +.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. +.\" 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. +.\" +.\" 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 2008-06-17 "Linux" "Linux Programmer's Manual" +.SH NAME +unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL \- Sockets for local +interprocess communication +.SH SYNOPSIS +.B #include <sys/socket.h> +.br +.B #include <sys/un.h> + +.IB unix_socket " = socket(PF_UNIX, type, 0);" +.br +.IB error " = socketpair(PF_UNIX, type, 0, int *" sv ");" +.SH DESCRIPTION +The +.B PF_UNIX +(also known as +.BR PF_LOCAL ) +socket family is used to communicate between processes on the same machine +efficiently. +Traditionally, Unix sockets can be either unnamed, +or bound to a file system pathname (marked as being of type socket). +Linux also supports an abstract namespace which is independent of the +file system. + +Valid types are: +.BR SOCK_STREAM , +for a stream-oriented socket and +.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 connection-oriented socket that preserves message boundaries +and delivers messages in the order that they were sent. + +Unix 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: +.in +4n +.nf + +#define UNIX_PATH_MAX 108 + +struct sockaddr_un { + sa_family_t sun_family; /* AF_UNIX */ + char sun_path[UNIX_PATH_MAX]; /* pathname */ +}; +.fi +.in +.PP +.I sun_family +always contains +.BR AF_UNIX . + +Three types of address are distinguished in this structure: +.IP * 3 +.IR pathname : +a Unix domain socket can be bound to a null-terminated file +system pathname using +.BR bind (2). +When the address of the socket is returned by +.BR getsockname (2), +.BR getpeername (2), +and +.BR accept (2), +its length is +.IR "sizeof(sa_family_t) + strlen(sun_path) + 1" , +and +.I sun_path +contains the null-terminated pathname. +.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 by +.BR getsockname (2), +.BR getpeername (2), +and +.BR accept (2), +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 by the fact that +.IR sun_path[0] +is a null byte ('\\0'). +All of the remaining bytes in +.I sun_path +define the "name" of the socket. +(Null bytes in the name have no special significance.) +The name has no connection with file system pathnames. +The socket's address in this namespace is given by the rest of the +bytes in +.IR sun_path . +When the address of an abstract socket is returned by +.BR getsockname (2), +.BR getpeername (2), +and +.BR accept (2), +its length is +.IR "sizeof(struct sockaddr_un)" , +and +.I sun_path +contains the abstract name. +The abstract socket namespace is a non-portable Linux extension. +.SS Socket Options +For historical reasons these socket options are specified with a +.B SOL_SOCKET +type even though they are +.B PF_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 +Enables the receiving of the credentials of the sending process +ancillary message. +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. +.SS (Un)supported Features +The following paragraphs describe domain-specific details and +unsupported features of the sockets API for Unix domain sockets on Linux. + +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)). + +The +.BR send (2) +.B MSG_MORE +flag is not supported by Unix domain sockets. + +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 PF_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. +The passed file descriptors behave as though they have been created with +.BR dup (2). +.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. + +.in +4n +.nf +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 */ +}; +.fi +.in + +The credentials which the sender specifies are checked by the kernel. +A process with effective user ID 0 is allowed to specify values that do +not match its own. +The sender must specify its own process ID (unless it has the capability +.BR CAP_SYS_ADMIN ), +its 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 +(unless it has +.BR CAP_SETGID ). +To receive a +.I struct ucred +message the +.B SO_PASSCRED +option must be enabled on the socket. +.SH ERRORS +.TP +.B EADDRINUSE +Selected local address is already taken or file system socket +object already exists. +.TP +.B ECONNREFUSED +.BR 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. +.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 the missing setting of AF_UNIX +in the +.I sun_type +field of passed addresses or the socket being 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 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 sendmsg (2) +or +.BR recvmsg (2). +.TP +.B EPROTONOSUPPORT +Passed protocol is not PF_UNIX. +.TP +.B EPROTOTYPE +Remote socket does not match the local socket type +.RB ( SOCK_DGRAM +vs. +.BR SOCK_STREAM ) +.TP +.B ESOCKTNOSUPPORT +Unknown socket type. +.PP +Other errors can be generated by the generic socket layer or +by the file system while generating a file system 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 +In the Linux implementation, sockets which are visible in the +file system honor the permissions of the directory they are in. +Their owner, group and their permissions can be changed. +Creation of a new socket will fail if the process does not have write and +search (execute) permission on the directory the socket is created in. +Connecting to the socket object requires read/write permission. +This behavior differs from many BSD-derived systems which +ignore permissions for Unix sockets. +Portable programs should not rely on +this feature for security. + +Binding to a socket with a filename creates a socket +in the file system 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 file system when the last +reference to it is closed. + +To pass file descriptors or credentials over a +.BR SOCK_STREAM , +you need +to send or receive at least one byte of non-ancillary data in the same +.BR sendmsg (2) +or +.BR recvmsg (2) +call. + +Unix domain stream sockets do not support the notion of out-of-band data. +.SH EXAMPLE +See +.BR bind (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) |