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