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