2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
|
|
|
.\"
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified, 2003-12-02, Michael Kerrisk, <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Modified, 2003-09-23, Adam Langley
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified, 2004-05-27, Michael Kerrisk, <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added SOCK_SEQPACKET
|
|
|
|
.\"
|
2007-05-18 10:09:18 +00:00
|
|
|
.TH UNIX 7 2004-05-27 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2007-04-12 22:42:49 +00:00
|
|
|
unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL \- Sockets for local
|
2006-12-27 03:54:41 +00:00
|
|
|
interprocess communication
|
2004-11-03 13:51:07 +00:00
|
|
|
.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
|
2007-04-12 22:42:49 +00:00
|
|
|
efficiently.
|
|
|
|
Unix sockets can be either anonymous (created by
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR socketpair (2))
|
2007-04-12 22:42:49 +00:00
|
|
|
or associated with a file of type socket.
|
2004-11-03 13:51:07 +00:00
|
|
|
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 kernel 2.6.4)
|
|
|
|
.BR SOCK_SEQPACKET ,
|
|
|
|
for a connection-oriented socket that preserves message boundaries
|
2007-04-12 22:42:49 +00:00
|
|
|
and delivers messages in the order that they were sent.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
Unix sockets support passing file descriptors or process credentials
|
2006-01-03 10:58:34 +00:00
|
|
|
to other processes using ancillary data.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SS Address Format
|
2007-04-12 22:42:49 +00:00
|
|
|
A Unix address is defined as a filename in the filesystem or
|
|
|
|
as a unique string in the abstract namespace.
|
|
|
|
Sockets created by
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR socketpair (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
are anonymous.
|
|
|
|
For non-anonymous sockets the target address can be set
|
2004-11-03 13:51:07 +00:00
|
|
|
using
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR connect (2).
|
2004-11-03 13:51:07 +00:00
|
|
|
The local address can be set using
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR bind (2).
|
2004-11-03 13:51:07 +00:00
|
|
|
When a socket is connected and it doesn't already have a local address a
|
2007-04-12 22:42:49 +00:00
|
|
|
unique address in the abstract namespace will be generated automatically.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2006-03-07 02:02:26 +00:00
|
|
|
.in +0.25i
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
2006-03-07 02:02:26 +00:00
|
|
|
#define UNIX_PATH_MAX 108
|
2004-11-03 13:51:07 +00:00
|
|
|
|
|
|
|
struct sockaddr_un {
|
2006-03-07 02:02:26 +00:00
|
|
|
sa_family_t sun_family; /* AF_UNIX */
|
|
|
|
char sun_path[UNIX_PATH_MAX]; /* pathname */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
2006-03-07 02:02:26 +00:00
|
|
|
.in -0.25i
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
.B sun_family
|
2004-11-03 13:51:07 +00:00
|
|
|
always contains
|
|
|
|
.BR AF_UNIX .
|
|
|
|
.B sun_path
|
|
|
|
contains the zero-terminated pathname of the socket in the file system.
|
2007-04-12 22:42:49 +00:00
|
|
|
If
|
2004-11-03 13:51:07 +00:00
|
|
|
.B sun_path
|
2007-04-12 22:42:49 +00:00
|
|
|
starts with a null byte (''\0'),
|
2006-01-13 02:09:44 +00:00
|
|
|
then it refers to the abstract namespace maintained by
|
2004-11-03 13:51:07 +00:00
|
|
|
the Unix protocol module.
|
2007-04-12 22:42:49 +00:00
|
|
|
The socket's address in this namespace is given by the rest of the
|
2006-01-03 10:58:34 +00:00
|
|
|
bytes in
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR sun_path .
|
|
|
|
Note that names in the abstract namespace are not zero-terminated.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SS Socket Options
|
2007-04-12 22:42:49 +00:00
|
|
|
For historical reasons these socket options are specified with a
|
2004-11-03 13:51:07 +00:00
|
|
|
SOL_SOCKET type even though they are PF_UNIX specific.
|
2007-04-12 22:42:49 +00:00
|
|
|
They can be set with
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR setsockopt (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
and read with
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR getsockopt (2)
|
|
|
|
by specifying SOL_SOCKET as the socket family.
|
|
|
|
.TP
|
|
|
|
.B SO_PASSCRED
|
2007-04-12 22:42:49 +00:00
|
|
|
Enables the receiving of the credentials of the sending process
|
|
|
|
ancillary message.
|
2006-01-03 10:58:34 +00:00
|
|
|
When this option is set and the socket is not yet connected
|
2004-11-03 13:51:07 +00:00
|
|
|
a unique name in the abstract namespace will be generated automatically.
|
2007-04-12 22:42:49 +00:00
|
|
|
Expects an integer boolean flag.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SS (Un)supported Features
|
2007-04-12 22:42:49 +00:00
|
|
|
The following paragraphs describe domain-specific details and
|
2005-12-15 12:46:18 +00:00
|
|
|
unsupported features of the sockets API for Unix domain sockets on Linux.
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
Unix domain sockets do not support the transmission of
|
|
|
|
out-of-band data (the
|
2005-12-14 16:36:17 +00:00
|
|
|
.B MSG_OOB
|
|
|
|
flag for
|
|
|
|
.BR send (2)
|
|
|
|
and
|
|
|
|
.BR recv (2)).
|
|
|
|
|
|
|
|
The
|
2005-12-15 12:46:18 +00:00
|
|
|
.BR send (2)
|
2005-12-14 16:36:17 +00:00
|
|
|
.B MSG_MORE
|
2006-07-19 12:55:37 +00:00
|
|
|
flag is not supported by Unix domain sockets.
|
2005-12-14 16:36:17 +00:00
|
|
|
|
2005-12-15 12:46:18 +00:00
|
|
|
The
|
|
|
|
.B SO_SNDBUF
|
2006-07-19 12:55:37 +00:00
|
|
|
socket option does have an effect for Unix domain sockets, but the
|
2005-12-15 12:46:18 +00:00
|
|
|
.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.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SS Ancillary Messages
|
2004-11-03 13:51:07 +00:00
|
|
|
Ancillary data is sent and received using
|
|
|
|
.BR sendmsg (2)
|
|
|
|
and
|
|
|
|
.BR recvmsg (2).
|
|
|
|
For historical reasons the ancillary message types listed below
|
2007-04-12 22:42:49 +00:00
|
|
|
are specified with a SOL_SOCKET type even though they are PF_UNIX
|
2006-01-03 10:58:34 +00:00
|
|
|
specific.
|
2004-11-03 13:51:07 +00:00
|
|
|
To send them set the
|
|
|
|
.B cmsg_level
|
2007-04-12 22:42:49 +00:00
|
|
|
field of the struct
|
2004-11-03 13:51:07 +00:00
|
|
|
.B cmsghdr
|
2007-04-12 22:42:49 +00:00
|
|
|
to SOL_SOCKET and the
|
|
|
|
.B cmsg_type
|
|
|
|
field to the type.
|
|
|
|
For more information see
|
|
|
|
.BR cmsg (3).
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B SCM_RIGHTS
|
2007-04-12 22:42:49 +00:00
|
|
|
Send or receive a set of open file descriptors from another process.
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
Send or receive Unix credentials.
|
|
|
|
This can be used for authentication.
|
|
|
|
The credentials are passed as a
|
2005-11-02 13:55:25 +00:00
|
|
|
.I struct ucred
|
2004-11-03 13:51:07 +00:00
|
|
|
ancillary message.
|
|
|
|
|
2006-03-07 02:02:26 +00:00
|
|
|
.in +0.25i
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
|
|
|
struct ucred {
|
2007-04-12 22:42:49 +00:00
|
|
|
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 */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
2006-03-07 02:02:26 +00:00
|
|
|
.in -0.25i
|
2007-04-12 22:42:49 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
The credentials which the sender specifies are checked by the kernel.
|
2007-04-12 22:42:49 +00:00
|
|
|
A process with effective user ID 0 is allowed to specify values that do
|
|
|
|
not match its own.
|
2004-11-03 13:51:07 +00:00
|
|
|
The sender must specify its own process ID (unless it has the capability
|
|
|
|
.BR CAP_SYS_ADMIN ),
|
2005-07-18 16:09:29 +00:00
|
|
|
its user ID, effective user ID, or saved set-user-ID (unless it has
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR CAP_SETUID ),
|
2007-04-12 22:42:49 +00:00
|
|
|
and its group ID, effective group ID, or saved set-group-ID
|
2006-01-03 10:58:34 +00:00
|
|
|
(unless it has
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR CAP_SETGID ).
|
|
|
|
To receive a
|
2005-11-02 13:55:25 +00:00
|
|
|
.I struct ucred
|
2004-11-03 13:51:07 +00:00
|
|
|
message the
|
2007-04-12 22:42:49 +00:00
|
|
|
.B SO_PASSCRED
|
2004-11-03 13:51:07 +00:00
|
|
|
option must be enabled on the socket.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
Out of memory.
|
|
|
|
.TP
|
|
|
|
.B ECONNREFUSED
|
|
|
|
.BR connect (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
called with a socket object that isn't listening.
|
|
|
|
This can happen when
|
2004-11-03 13:51:07 +00:00
|
|
|
the remote socket does not exist or the filename is not a socket.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2006-01-03 10:58:34 +00:00
|
|
|
invalid state for the applied operation.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EOPNOTSUPP
|
2007-04-12 22:42:49 +00:00
|
|
|
Stream operation called on non-stream oriented socket or tried to
|
2004-11-03 13:51:07 +00:00
|
|
|
use the out-of-band data option.
|
|
|
|
.TP
|
|
|
|
.B EPROTONOSUPPORT
|
|
|
|
Passed protocol is not PF_UNIX.
|
|
|
|
.TP
|
|
|
|
.B ESOCKTNOSUPPORT
|
|
|
|
Unknown socket type.
|
2007-04-12 22:42:49 +00:00
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EPROTOTYPE
|
|
|
|
Remote socket does not match the local socket type (SOCK_DGRAM vs.
|
|
|
|
SOCK_STREAM)
|
|
|
|
.TP
|
|
|
|
.B EADDRINUSE
|
2007-04-12 22:42:49 +00:00
|
|
|
Selected local address is already taken or filesystem socket
|
|
|
|
object already exists.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EISCONN
|
|
|
|
.BR connect (2)
|
|
|
|
called on an already connected socket or a target address was
|
|
|
|
specified on a connected socket.
|
|
|
|
.TP
|
|
|
|
.B ENOTCONN
|
|
|
|
Socket operation needs a target address, but the socket is not connected.
|
|
|
|
.TP
|
|
|
|
.B ECONNRESET
|
|
|
|
Remote socket was unexpectedly closed.
|
|
|
|
.TP
|
|
|
|
.B EPIPE
|
2007-04-12 22:42:49 +00:00
|
|
|
Remote socket was closed on a stream socket.
|
|
|
|
If enabled, a
|
|
|
|
.B SIGPIPE
|
|
|
|
is sent as well.
|
|
|
|
This can be avoided by passing the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B MSG_NOSIGNAL
|
|
|
|
flag to
|
|
|
|
.BR sendmsg (2)
|
|
|
|
or
|
|
|
|
.BR recvmsg (2).
|
|
|
|
.TP
|
|
|
|
.B EFAULT
|
|
|
|
User memory address was not valid.
|
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
The sender passed invalid credentials in the
|
2005-11-02 13:55:25 +00:00
|
|
|
.IR "struct ucred" .
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2007-04-12 22:42:49 +00:00
|
|
|
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.
|
2007-05-19 04:30:20 +00:00
|
|
|
.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
|
|
|
|
filesystem honour 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 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.
|
2007-05-28 15:50:37 +00:00
|
|
|
.SH EXAMPLE
|
|
|
|
See
|
|
|
|
.BR bind (2).
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR recvmsg (2),
|
|
|
|
.BR sendmsg (2),
|
|
|
|
.BR socket (2),
|
|
|
|
.BR socketpair (2),
|
|
|
|
.BR cmsg (3),
|
|
|
|
.BR capabilities (7),
|
|
|
|
.BR socket (7)
|