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$ 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 42The 43.Fn getpeereid 44function returns the effective user and group IDs of the 45peer connected to a 46.Ux Ns -domain 47socket. 48The argument 49.Fa s 50must be a 51.Ux Ns -domain 52socket 53.Pq Xr unix 4 54of type 55.Dv SOCK_STREAM 56on which either 57.Xr connect 2 58or 59.Xr listen 2 60have been called. 61The effective used ID is placed in 62.Fa euid , 63and the effective group ID in 64.Fa egid . 65.Pp 66The credentials returned to the 67.Xr listen 2 68caller are those of its peer at the time it called 69.Xr connect 2 ; 70the credentials returned to the 71.Xr connect 2 72caller are those of its peer at the time it called 73.Xr listen 2 . 74This mechanism is reliable; there is no way for either side to influence 75the credentials returned to its peer except by calling the appropriate 76system call (i.e., either 77.Xr connect 2 78or 79.Xr listen 2 ) 80under different effective credentials. 81.Pp 82One common use of this routine is for a 83.Ux Ns -domain 84server 85to verify the credentials of its client. 86Likewise, the client can verify the credentials of the server. 87.Sh IMPLEMENTATION NOTES 88On 89.Fx , 90.Fn getpeereid 91is implemented in terms of the 92.Dv LOCAL_PEERCRED 93.Xr unix 4 94socket option. 95.Sh RETURN VALUES 96.Rv -std getpeereid 97.Sh ERRORS 98The 99.Fn getpeereid 100function 101fails if: 102.Bl -tag -width Er 103.It Bq Er EBADF 104The argument 105.Fa s 106is not a valid descriptor. 107.It Bq Er ENOTSOCK 108The argument 109.Fa s 110is a file, not a socket. 111.It Bq Er ENOTCONN 112The argument 113.Fa s 114does not refer to a socket on which 115.Xr connect 2 116or 117.Xr listen 2 118have been called. 119.It Bq Er EINVAL 120The argument 121.Fa s 122does not refer to a socket of type 123.Dv SOCK_STREAM , 124or the kernel returned invalid data. 125.El 126.Sh SEE ALSO 127.Xr connect 2 , 128.Xr getpeername 2 , 129.Xr getsockname 2 , 130.Xr getsockopt 2 , 131.Xr listen 2 , 132.Xr unix 4 133.Sh HISTORY 134The 135.Fn getpeereid 136function appeared in 137.Fx 4.6 . 138