lib/libc/getpeername.2

   1 .\"     $OpenBSD: getpeername.2,v 1.26 2015/09/10 17:55:21 schwarze Exp $
   2 .\"     $NetBSD: getpeername.2,v 1.6 1995/10/12 15:40:56 jtc Exp $
   3 .\"
   4 .\" Copyright (c) 1983, 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)getpeername.2       8.1 (Berkeley) 6/4/93
  32 .\"
  33 .Dd October 24, 2016
  34 .Dt GETPEERNAME 2
  35 .Os
  36 .Sh NAME
  37 .Nm getpeername
  38 .Nd get name of connected peer
  39 .Sh SYNOPSIS
  40 .In sys/socket.h
  41 .Ft int
  42 .Fn getpeername "int s" "struct sockaddr *name" "socklen_t *namelen"
  43 .Sh DESCRIPTION
  44 .Fn getpeername
  45 returns the address information of the peer connected to socket
  46 .Fa s .
  47 One common use occurs when a process inherits an open socket, such as
  48 TCP servers forked from
  49 .Xr inetd 8 .
  50 In this scenario,
  51 .Fn getpeername
  52 is used to determine the connecting client's IP address.
  53 .Pp
  54 .Fn getpeername
  55 takes three parameters:
  56 .Pp
  57 .Fa s
  58 contains the file descriptor of the socket whose peer should be looked up.
  59 .Pp
  60 .Fa name
  61 points to a
  62 .Li sockaddr
  63 structure that will hold the address information for the connected peer.
  64 Normal use requires one to use a structure
  65 specific to the protocol family in use, such as
  66 .Li sockaddr_in
  67 (IPv4) or
  68 .Li sockaddr_in6
  69 (IPv6), cast to a (struct sockaddr *).
  70 .Pp
  71 For greater portability, especially with the newer protocol families, the new
  72 .Li struct sockaddr_storage
  73 should be used.
  74 .Li sockaddr_storage
  75 is large enough to hold any of the other sockaddr_* variants.
  76 On return, it can be cast to the correct sockaddr type,
  77 based on the protocol family contained in its ss_family field.
  78 .Pp
  79 .Fa namelen
  80 indicates the amount of space pointed to by
  81 .Fa name ,
  82 in bytes.
  83 .Pp
  84 If address information for the local end of the socket is required, the
  85 .Xr getsockname 2
  86 function should be used instead.
  87 .Pp
  88 If
  89 .Fa name
  90 does not point to enough space to hold the entire socket address, the
  91 result will be truncated to
  92 .Fa namelen
  93 bytes.
  94 .Sh RETURN VALUES
  95 If the call succeeds, a 0 is returned and
  96 .Fa namelen
  97 is set to the actual size of the socket address returned in
  98 .Fa name .
  99 Otherwise,
 100 .Va errno
 101 is set and a value of \-1 is returned.
 102 .Sh ERRORS
 103 On failure,
 104 .Va errno
 105 is set to one of the following:
 106 .Bl -tag -width Er
 107 .It Bq Er EBADF
 108 The argument
 109 .Fa s
 110 is not a valid descriptor.
 111 .It Bq Er ENOTSOCK
 112 The argument
 113 .Fa s
 114 is a file, not a socket.
 115 .It Bq Er ENOTCONN
 116 The socket is not connected.
 117 .It Bq Er ENOBUFS
 118 Insufficient resources were available in the system
 119 to perform the operation.
 120 .It Bq Er EFAULT
 121 The
 122 .Fa name
 123 or
 124 .Fa namelen
 125 parameter points to memory not in a valid part of the
 126 process address space.
 127 .It Bq Er EINVAL
 128 The socket has been shut down.
 129 .El
 130 .Sh SEE ALSO
 131 .Xr accept 2 ,
 132 .Xr bind 2 ,
 133 .Xr getsockname 2 ,
 134 .Xr socket 2 ,
 135 .Xr getpeereid 3
 136 .Sh STANDARDS
 137 The
 138 .Fn getpeername
 139 function conforms to
 140 .St -p1003.1-2008 .
 141 .Sh HISTORY
 142 The
 143 .Fn getpeername
 144 function call appeared in
 145 .Bx 4.2 .