lib/libc/getsockname.2

   1 .\"     $OpenBSD: getsockname.2,v 1.30 2015/09/10 17:55:21 schwarze Exp $
   2 .\"     $NetBSD: getsockname.2,v 1.6 1995/10/12 15:41:00 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 .\"     @(#)getsockname.2       8.1 (Berkeley) 6/4/93
  32 .\"
  33 .Dd $Mdocdate: September 10 2015 $
  34 .Dt GETSOCKNAME 2
  35 .Os
  36 .Sh NAME
  37 .Nm getsockname
  38 .Nd get socket name
  39 .Sh SYNOPSIS
  40 .In sys/socket.h
  41 .Ft int
  42 .Fn getsockname "int s" "struct sockaddr *name" "socklen_t *namelen"
  43 .Sh DESCRIPTION
  44 .Fn getsockname
  45 returns the locally bound address information for a specified socket.
  46 .Pp
  47 Common uses of this function are as follows:
  48 .Bl -bullet
  49 .It
  50 When
  51 .Xr bind 2
  52 is called with a port number of 0 (indicating the kernel should pick
  53 an ephemeral port)
  54 .Fn getsockname
  55 is used to retrieve the kernel-assigned port number.
  56 .It
  57 When a process calls
  58 .Xr bind 2
  59 on a wildcard IP address,
  60 .Fn getsockname
  61 is used to retrieve the local IP address for the connection.
  62 .It
  63 When a function wishes to know the address family of a socket,
  64 .Fn getsockname
  65 can be used.
  66 .El
  67 .Pp
  68 .Fn getsockname
  69 takes three parameters:
  70 .Pp
  71 .Fa s
  72 contains the file descriptor for the socket to be looked up.
  73 .Pp
  74 .Fa name
  75 points to a
  76 .Li sockaddr
  77 structure which will hold the resulting address information.
  78 Normal use requires one to use a structure
  79 specific to the protocol family in use, such as
  80 .Li sockaddr_in
  81 (IPv4) or
  82 .Li sockaddr_in6
  83 (IPv6), cast to a (struct sockaddr *).
  84 .Pp
  85 For greater portability (such as newer protocol families) the new
  86 structure sockaddr_storage exists.
  87 .Li sockaddr_storage
  88 is large enough to hold any of the other sockaddr_* variants.
  89 On return, it should be cast to the correct sockaddr type,
  90 according to the current protocol family.
  91 .Pp
  92 .Fa namelen
  93 indicates the amount of space pointed to by
  94 .Fa name ,
  95 in bytes.
  96 Upon return,
  97 .Fa namelen
  98 is set to the actual size of the returned address information.
  99 .Pp
 100 If the address of the destination socket for a given socket connection is
 101 needed, the
 102 .Xr getpeername 2
 103 function should be used instead.
 104 .Pp
 105 If
 106 .Fa name
 107 does not point to enough space to hold the entire socket address, the
 108 result will be truncated to
 109 .Fa namelen
 110 bytes.
 111 .Sh RETURN VALUES
 112 On success,
 113 .Fn getsockname
 114 returns a 0, and
 115 .Fa namelen
 116 is set to the actual size of the socket address returned in
 117 .Fa name .
 118 Otherwise,
 119 .Va errno
 120 is set, and a value of \-1 is returned.
 121 .Sh ERRORS
 122 If
 123 .Fn getsockname
 124 fails,
 125 .Va errno
 126 is set to one of the following:
 127 .Bl -tag -width Er
 128 .It Bq Er EBADF
 129 The argument
 130 .Fa s
 131 is not a valid descriptor.
 132 .It Bq Er ENOTSOCK
 133 The argument
 134 .Fa s
 135 is a file, not a socket.
 136 .It Bq Er ENOBUFS
 137 Insufficient resources were available in the system
 138 to perform the operation.
 139 .It Bq Er EFAULT
 140 The
 141 .Fa name
 142 or
 143 .Fa namelen
 144 parameter points to memory not in a valid part of the
 145 process address space.
 146 .It Bq Er EINVAL
 147 The socket has been shut down.
 148 .El
 149 .Sh SEE ALSO
 150 .Xr accept 2 ,
 151 .Xr bind 2 ,
 152 .Xr getpeername 2 ,
 153 .Xr socket 2 ,
 154 .Xr getpeereid 3
 155 .Sh STANDARDS
 156 The
 157 .Fn getsockname
 158 function conforms to
 159 .St -p1003.1-2008 .
 160 .Sh HISTORY
 161 The
 162 .Fn getsockname
 163 function call appeared in
 164 .Bx 4.2 .