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