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.5.2.2 2003/03/13 18:05:37 trhodes Exp $ 27.\" $DragonFly: src/lib/libc/gen/getpeereid.3,v 1.3 2004/03/11 12:28:50 hmp Exp $ 28.\" 29.Dd July 15, 2001 30.Dt GETPEEREID 3 31.Os 32.Sh NAME 33.Nm getpeereid 34.Nd get the effective credentials of a UNIX-domain peer 35.Sh LIBRARY 36.Lb libc 37.Sh SYNOPSIS 38.In sys/types.h 39.In unistd.h 40.Ft int 41.Fn getpeereid "int s" "uid_t *euid" "gid_t *egid" 42.Sh DESCRIPTION 43The 44.Fn getpeereid 45function returns the effective user and group IDs of the 46peer connected to a 47.Ux Ns -domain 48socket. 49The argument 50.Fa s 51must be a 52.Ux Ns -domain 53socket 54.Pq Xr unix 4 55of type 56.Dv SOCK_STREAM 57on which either 58.Xr connect 2 59or 60.Xr listen 2 61have been called. 62The effective used ID is placed in 63.Fa euid , 64and the effective group ID in 65.Fa egid . 66.Pp 67The credentials returned to the 68.Xr listen 2 69caller are those of its peer at the time it called 70.Xr connect 2 ; 71the credentials returned to the 72.Xr connect 2 73caller are those of its peer at the time it called 74.Xr listen 2 . 75This mechanism is reliable; there is no way for either side to influence 76the credentials returned to its peer except by calling the appropriate 77system call (i.e., either 78.Xr connect 2 79or 80.Xr listen 2 ) 81under different effective credentials. 82.Pp 83One common use of this routine is for a 84.Ux Ns -domain 85server 86to verify the credentials of its client. 87Likewise, the client can verify the credentials of the server. 88.Sh IMPLEMENTATION NOTES 89On 90.Dx , 91.Fn getpeereid 92is implemented in terms of the 93.Dv LOCAL_PEERCRED 94.Xr unix 4 95socket option. 96.Sh RETURN VALUES 97.Rv -std getpeereid 98.Sh ERRORS 99The 100.Fn getpeereid 101function 102fails if: 103.Bl -tag -width Er 104.It Bq Er EBADF 105The argument 106.Fa s 107is not a valid descriptor. 108.It Bq Er ENOTSOCK 109The argument 110.Fa s 111is a file, not a socket. 112.It Bq Er ENOTCONN 113The argument 114.Fa s 115does not refer to a socket on which 116.Xr connect 2 117or 118.Xr listen 2 119have been called. 120.It Bq Er EINVAL 121The argument 122.Fa s 123does not refer to a socket of type 124.Dv SOCK_STREAM , 125or the kernel returned invalid data. 126.El 127.Sh SEE ALSO 128.Xr connect 2 , 129.Xr getpeername 2 , 130.Xr getsockname 2 , 131.Xr getsockopt 2 , 132.Xr listen 2 , 133.Xr unix 4 134.Sh HISTORY 135The 136.Fn getpeereid 137function appeared in 138.Fx 4.6 . 139