lib/libc/sys/getpeername.2

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