diff options
author | glebius <glebius@FreeBSD.org> | 2012-11-16 14:00:27 +0000 |
---|---|---|
committer | glebius <glebius@FreeBSD.org> | 2012-11-16 14:00:27 +0000 |
commit | ce1649229755ee3a92afba592a235461bcccf174 (patch) | |
tree | ee85473e2fff3723e86a77c310a41adc74c3c68a /share/man/man4/unix.4 | |
parent | f81cc6662509ddec4578b29f294375340c8ae404 (diff) | |
download | FreeBSD-src-ce1649229755ee3a92afba592a235461bcccf174.zip FreeBSD-src-ce1649229755ee3a92afba592a235461bcccf174.tar.gz |
o Remove meaningless PROTOCOLS section.
o Describe passing file descriptors as separate section.
- Descriptors can be passed through any protocol of the UNIX family,
not SOCK_STREAM and SOCK_SEQPACKET only. [1]
o Describe socket options as separate section.
- Move LOCAL_PEERCRED option to this section.
- Describe struct xucred.
- In LOCAL_CREDS section mention that credentials
are passed only on the first read on non-datagram
sockets.
o Xref all mentioned system calls.
Noticed by: Igor Sysoev [1]
Diffstat (limited to 'share/man/man4/unix.4')
-rw-r--r-- | share/man/man4/unix.4 | 108 |
1 files changed, 65 insertions, 43 deletions
diff --git a/share/man/man4/unix.4 b/share/man/man4/unix.4 index 97e797c..7ad3ded 100644 --- a/share/man/man4/unix.4 +++ b/share/man/man4/unix.4 @@ -32,7 +32,7 @@ .\" @(#)unix.4 8.1 (Berkeley) 6/9/93 .\" $FreeBSD$ .\" -.Dd October 5, 2009 +.Dd November 16, 2012 .Dt UNIX 4 .Os .Sh NAME @@ -123,20 +123,10 @@ of a or .Xr sendto 2 must be writable. -.Sh PROTOCOLS +.Sh PASSING FILE DESCRIPTORS The .Ux Ns -domain -protocol family is comprised of simple -transport protocols that support the -.Dv SOCK_STREAM , -.Dv SOCK_SEQPACKET , -and -.Dv SOCK_DGRAM -abstractions. -.Dv SOCK_STREAM -and -.Dv SOCK_SEQPACKET -sockets also support the communication of +sockets support the communication of .Ux file descriptors through the use of the .Va msg_control @@ -173,36 +163,7 @@ passed to a receiver. Descriptors that are awaiting delivery, or that are purposely not received, are automatically closed by the system when the destination socket is closed. -.Pp -The effective credentials (i.e., the user ID and group list) of a -peer on a -.Dv SOCK_STREAM -socket may be obtained using the -.Dv LOCAL_PEERCRED -socket option. -This may be used by a server to obtain and verify the credentials of -its client, and vice versa by the client to verify the credentials -of the server. -These will arrive in the form of a filled in -.Vt "struct xucred" -(defined in -.In sys/ucred.h ) . -The credentials presented to the server (the -.Xr listen 2 -caller) are those of the client when it called -.Xr connect 2 ; -the credentials presented to the client (the -.Xr connect 2 -caller) are those of the server when it called -.Xr listen 2 . -This mechanism is reliable; there is no way for either party to influence -the credentials presented to its peer except by calling the appropriate -system call (e.g., -.Xr connect 2 -or -.Xr listen 2 ) -under different effective credentials. -.Pp +.Sh SOCKET OPTIONS .Tn UNIX domain sockets support a number of socket options which can be set with .Xr setsockopt 2 @@ -256,6 +217,13 @@ cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups)) cmsg_level = SOL_SOCKET cmsg_type = SCM_CREDS .Ed +.Pp +On +.Dv SOCK_STREAM +and +.Dv SOCK_SEQPACKET +sockets credentials are passed only on the first read from a socket, +then system clears the option on socket. .It Dv LOCAL_CONNWAIT Used with .Dv SOCK_STREAM @@ -264,8 +232,62 @@ sockets, this option causes the function to block until .Xr accept 2 has been called on the listening socket. +.It Dv LOCAL_PEERCRED +Requested via +.Xr getsockopt 2 +on a +.Dv SOCK_STREAM +socket returns credentials of the remote side. +These will arrive in the form of a filled in +.Vt xucred +structure, defined in +.In sys/ucred.h +as follows: +.Bd -literal +struct xucred { + u_int cr_version; /* structure layout version */ + uid_t cr_uid; /* effective user id */ + short cr_ngroups; /* number of groups */ + gid_t cr_groups[XU_NGROUPS]; /* groups */ +}; +.Ed +The +.Vt cr_version +fields should be checked against +.Dv XUCRED_VERSION +define. +.Pp +The credentials presented to the server (the +.Xr listen 2 +caller) are those of the client when it called +.Xr connect 2 ; +the credentials presented to the client (the +.Xr connect 2 +caller) are those of the server when it called +.Xr listen 2 . +This mechanism is reliable; there is no way for either party to influence +the credentials presented to its peer except by calling the appropriate +system call (e.g., +.Xr connect 2 +or +.Xr listen 2 ) +under different effective credentials. +.Pp +To reliably obtain peer credentials on a +.Dv SOCK_DGRAM +socket refer to the +.Dv LOCAL_CREDS +socket option. .El .Sh SEE ALSO +.Xr connect 2 , +.Xr dup 2 , +.Xr fcntl 2 , +.Xr getsockopt 2 , +.Xr listen 2 , +.Xr recvmsg 2 , +.Xr sendto 2 , +.Xr setsockopt 2 , .Xr socket 2 , .Xr intro 4 .Rs |