man2/getpeername.2

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