lib/libc/rpc/bindresvport.3

   1 .\"     $OpenBSD: bindresvport.3,v 1.25 2013/06/05 03:39:23 tedu Exp $
   2 .\"
   3 .\" Copyright (c) 2010, Oracle America, Inc.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions are
   7 .\" met:
   8 .\"
   9 .\"     * Redistributions of source code must retain the above copyright
  10 .\"       notice, this list of conditions and the following disclaimer.
  11 .\"     * Redistributions in binary form must reproduce the above
  12 .\"       copyright notice, this list of conditions and the following
  13 .\"       disclaimer in the documentation and/or other materials
  14 .\"       provided with the distribution.
  15 .\"     * Neither the name of the "Oracle America, Inc." nor the names of its
  16 .\"       contributors may be used to endorse or promote products derived
  17 .\"       from this software without specific prior written permission.
  18 .\"
  19 .\"   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\"   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\"   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\"   FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  23 .\"   COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  24 .\"   INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\"   DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  26 .\"   GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  27 .\"   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28 .\"   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  29 .\"   NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30 .\"   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .Dd $Mdocdate: June 5 2013 $
  33 .Dt BINDRESVPORT 3
  34 .Os
  35 .Sh NAME
  36 .Nm bindresvport ,
  37 .Nm bindresvport_sa
  38 .Nd bind a socket to a privileged IP port
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In netinet/in.h
  42 .Ft int
  43 .Fn bindresvport "int sd" "struct sockaddr_in *sin"
  44 .Ft int
  45 .Fn bindresvport_sa "int sd" "struct sockaddr *sa"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn bindresvport
  49 and
  50 .Fn bindresvport_sa
  51 functions are used to bind a socket descriptor to a privileged IP
  52 port, that is, a port number in the range 0-1023.
  53 The
  54 .Fn bindresvport
  55 function operates solely on
  56 .Dv AF_INET
  57 sockets, whereas the
  58 .Fn bindresvport_sa
  59 function is capable of binding both
  60 .Dv AF_INET
  61 and
  62 .Dv AF_INET6
  63 sockets.
  64 .Pp
  65 Only the superuser may bind to a privileged port;
  66 these functions will fail for any other user.
  67 .Pp
  68 .Fa sd
  69 should be a socket descriptor that was returned by a call to
  70 .Xr socket 2 .
  71 .Pp
  72 If
  73 .Va sin
  74 is not the NULL pointer,
  75 .Va sin->sin_family
  76 must be initialized to the address family of the socket
  77 .Va sd .
  78 If the value of
  79 .Va sin->sin_port
  80 is non-zero,
  81 .Fn bindresvport
  82 will attempt to use the specified port.
  83 Otherwise, a free port in the range 600-1023 will be chosen and,
  84 if the
  85 .Xr bind 2
  86 succeeds,
  87 .Va sin->sin_port
  88 will be updated with the port that was assigned.
  89 .Pp
  90 If
  91 .Va sin
  92 is the NULL pointer, a free port in the range 600-1023 will be chosen
  93 (as above), but in this case there is no way for
  94 .Fn bindresvport
  95 to communicate to the caller which port was assigned.
  96 .Sh RETURN VALUES
  97 .Fn bindresvport
  98 returns 0 if it is successful, otherwise \-1 is returned and
  99 .Va errno
 100 set to reflect the cause of the error.
 101 .Sh ERRORS
 102 The
 103 .Fn bindresvport
 104 function fails if:
 105 .Bl -tag -width Er
 106 .It Bq Er EBADF
 107 .Fa sd
 108 is not a valid descriptor.
 109 .It Bq Er ENOTSOCK
 110 .Fa sd
 111 is not a socket.
 112 .It Bq Er EADDRNOTAVAIL
 113 The specified address is not available from the local machine.
 114 .It Bq Er EADDRINUSE
 115 The specified address is already in use.
 116 .It Bq Er EINVAL
 117 The socket is already bound to an address.
 118 .It Bq Er EINVAL
 119 The family of the socket and that requested in
 120 .Va sa->sa_family
 121 are not equivalent.
 122 .It Bq Er EACCES
 123 The requested address is protected, and the current user
 124 has inadequate permission to access it.
 125 .It Bq Er EFAULT
 126 The
 127 .Fa name
 128 parameter is not in a valid part of the user
 129 address space.
 130 .It Bq Er ENOBUFS
 131 Insufficient resources were available in the system
 132 to perform the operation.
 133 .It Bq Er EPFNOSUPPORT
 134 The protocol family has not been configured into the
 135 system, no implementation for it exists,
 136 or address family did not match between arguments.
 137 .El
 138 .Sh SEE ALSO
 139 .Xr bind 2 ,
 140 .Xr socket 2 ,
 141 .Xr rresvport 3 ,
 142 .Xr rresvport_af 3