]> git.saurik.com Git - apple/libc.git/blob - gen/getpeereid.3
Libc-262.3.2.tar.gz
[apple/libc.git] / gen / getpeereid.3
1 .\"
2 .\" Copyright (c) 2001 Dima Dorfman.
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\"
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 .\" SUCH DAMAGE.
25 .\"
26 .\" $FreeBSD: src/lib/libc/gen/getpeereid.3,v 1.2 2001/08/21 19:32:47 dd Exp $
27 .\"
28 .Dd July 15, 2001
29 .Dt GETPEEREID 3
30 .Os
31 .Sh NAME
32 .Nm getpeereid
33 .Nd get the effective credentials of a UNIX-domain peer
34 .Sh LIBRARY
35 .Lb libc
36 .Sh SYNOPSIS
37 .In sys/types.h
38 .In unistd.h
39 .Ft int
40 .Fn getpeereid "int s" "uid_t *euid" "gid_t *egid"
41 .Sh DESCRIPTION
42 The
43 .Fn getpeereid
44 function returns the effective user and group IDs of the
45 peer connected to a
46 .Ux Ns -domain
47 socket.
48 The argument
49 .Fa s
50 must be a
51 .Ux Ns -domain
52 socket
53 .Pq Xr unix 4
54 of type
55 .Dv SOCK_STREAM
56 on which either
57 .Xr connect 2
58 or
59 .Xr listen 2
60 have been called.
61 The effective used ID is placed in
62 .Fa euid ,
63 and the effective group ID in
64 .Fa egid .
65 .Pp
66 The credentials returned to the
67 .Xr listen 2
68 caller are those of its peer at the time it called
69 .Xr connect 2 ;
70 the credentials returned to the
71 .Xr connect 2
72 caller are those of its peer at the time it called
73 .Xr listen 2 .
74 This mechanism is reliable; there is no way for either side to influence
75 the credentials returned to its peer except by calling the appropriate
76 system call (i.e., either
77 .Xr connect 2
78 or
79 .Xr listen 2 )
80 under different effective credentials.
81 .Pp
82 One common use of this routine is for a
83 .Ux Ns -domain
84 server
85 to verify the credentials of its client.
86 Likewise, the client can verify the credentials of the server.
87 .Sh IMPLEMENTATION NOTES
88 On
89 .Fx ,
90 .Fn getpeereid
91 is implemented in terms of the
92 .Dv LOCAL_PEERCRED
93 .Xr unix 4
94 socket option.
95 .Sh RETURN VALUES
96 .Rv -std getpeerid
97 .Sh ERRORS
98 .Fn getpeerid
99 fails if:
100 .Bl -tag -width Er
101 .It Bq Er EBADF
102 The argument
103 .Fa s
104 is not a valid descriptor.
105 .It Bq Er ENOTSOCK
106 The argument
107 .Fa s
108 is a file, not a socket.
109 .It Bq Er ENOTCONN
110 The argument
111 .Fa s
112 does not refer to a socket on which
113 .Xr connect 2
114 or
115 .Xr listen 2
116 have been called.
117 .It Bq Er EINVAL
118 The argument
119 .Fa s
120 does not refer to a socket of type
121 .Dv SOCK_STREAM .
122 .El
123 .Sh SEE ALSO
124 .Xr connect 2 ,
125 .Xr getpeername 2 ,
126 .Xr getsockname 2 ,
127 .Xr getsockopt 2 ,
128 .Xr listen 2 ,
129 .Xr unix 4
130 .Sh HISTORY
131 The
132 .Fn getpeereid
133 function appeared in
134 .Fx 5.0 .