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 (date) "Linux man-pages (unreleased)"
  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 .P
  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 .P
  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-2008.
  80 .SH HISTORY
  81 POSIX.1-2001, SVr4, 4.4BSD
  82 (first appeared in 4.2BSD).
  83 .SH NOTES
  84 For stream sockets, once a
  85 .BR connect (2)
  86 has been performed, either socket can call
  87 .BR getpeername ()
  88 to obtain the address of the peer socket.
  89 On the other hand, datagram sockets are connectionless.
  90 Calling
  91 .BR connect (2)
  92 on a datagram socket merely sets the peer address for outgoing
  93 datagrams sent with
  94 .BR write (2)
  95 or
  96 .BR recv (2).
  97 The caller of
  98 .BR connect (2)
  99 can use
 100 .BR getpeername ()
 101 to obtain the peer address that it earlier set for the socket.
 102 However, the peer socket is unaware of this information, and calling
 103 .BR getpeername ()
 104 on the peer socket will return no useful information (unless a
 105 .BR connect (2)
 106 call was also executed on the peer).
 107 Note also that the receiver of a datagram can obtain
 108 the address of the sender when using
 109 .BR recvfrom (2).
 110 .SH SEE ALSO
 111 .BR accept (2),
 112 .BR bind (2),
 113 .BR getsockname (2),
 114 .BR ip (7),
 115 .BR socket (7),
 116 .BR unix (7)