Debian Codegraph @

upstream/debian-unstable/man2/getpeername.2

raw
1 .\" Copyright 1983-1991, The Regents of the University of California.
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
5 .\"
6 .TH getpeername 2 2025-10-29 "Linux man-pages 6.18"
7 .SH NAME
8 getpeername \- get name of connected peer socket
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/socket.h>
15 .P
16 .BI "int getpeername(int " sockfd ", struct sockaddr *restrict " addr ,
17 .BI " socklen_t *restrict " addrlen );
18 .fi
19 .SH DESCRIPTION
20 .BR getpeername ()
21 returns the address of the peer connected to the socket
22 .IR sockfd ,
23 in the buffer pointed to by
24 .IR addr .
25 The
26 .I addrlen
27 argument should be initialized to indicate the amount of space pointed to
28 by
29 .IR addr .
30 On return it contains the actual size of the name returned (in bytes).
31 The name is truncated if the buffer provided is too small.
32 .P
33 The returned address is truncated if the buffer provided is too small;
34 in this case,
35 .I addrlen
36 will return a value greater than was supplied to the call.
37 .SH RETURN VALUE
38 On success, zero is returned.
39 On error, \-1 is returned, and
40 .I errno
41 is set to indicate the error.
42 .SH ERRORS
43 .TP
44 .B EBADF
45 The argument
46 .I sockfd
47 is not a valid file descriptor.
48 .TP
49 .B EFAULT
50 The
51 .I addr
52 argument points to memory not in a valid part of the
53 process address space.
54 .TP
55 .B EINVAL
56 .I addrlen
57 is invalid (e.g., is negative).
58 .TP
59 .B ENOBUFS
60 Insufficient resources were available in the system
61 to perform the operation.
62 .TP
63 .B ENOTCONN
64 The socket is not connected.
65 .TP
66 .B ENOTSOCK
67 The file descriptor
68 .I sockfd
69 does not refer to a socket.
70 .SH STANDARDS
71 POSIX.1-2024.
72 .SH HISTORY
73 POSIX.1-2001, SVr4, 4.4BSD
74 (first appeared in 4.2BSD).
75 .SH NOTES
76 For stream sockets, once a
77 .BR connect (2)
78 has been performed, either socket can call
79 .BR getpeername ()
80 to obtain the address of the peer socket.
81 On the other hand, datagram sockets are connectionless.
82 Calling
83 .BR connect (2)
84 on a datagram socket merely sets the peer address for outgoing
85 datagrams sent with
86 .BR write (2)
87 or
88 .BR recv (2).
89 The caller of
90 .BR connect (2)
91 can use
92 .BR getpeername ()
93 to obtain the peer address that it earlier set for the socket.
94 However, the peer socket is unaware of this information, and calling
95 .BR getpeername ()
96 on the peer socket will return no useful information (unless a
97 .BR connect (2)
98 call was also executed on the peer).
99 Note also that the receiver of a datagram can obtain
100 the address of the sender when using
101 .BR recvfrom (2).
102 .SH SEE ALSO
103 .BR accept (2),
104 .BR bind (2),
105 .BR getsockname (2),
106 .BR ip (7),
107 .BR socket (7),
108 .BR unix (7)