diff options
Diffstat (limited to 'man7/unix.7')
| -rw-r--r-- | man7/unix.7 | 367 |
1 files changed, 8 insertions, 359 deletions
diff --git a/man7/unix.7 b/man7/unix.7 index 3f66b37427..631a99c5a8 100644 --- a/man7/unix.7 +++ b/man7/unix.7 @@ -1,359 +1,8 @@ -.\" 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) +.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" |