lib/libc/rpc/bindresvport.3

   1 .\"     @(#)bindresvport.3n     2.2 88/08/02 4.0 RPCSRC; from 1.7 88/03/14 SMI
   2 .\"     $NetBSD: bindresvport.3,v 1.13 2007/01/27 07:58:47 cbiere Exp $
   3 .\"
   4 .Dd January 27, 2007
   5 .Dt BINDRESVPORT 3
   6 .Os
   7 .Sh NAME
   8 .Nm bindresvport ,
   9 .Nm bindresvport_sa
  10 .Nd bind a socket to a reserved privileged IP port
  11 .Sh LIBRARY
  12 .Lb libc
  13 .Sh SYNOPSIS
  14 .In sys/types.h
  15 .In rpc/rpc.h
  16 .Ft int
  17 .Fn bindresvport "int sd" "struct sockaddr_in *sin"
  18 .Ft int
  19 .Fn bindresvport_sa "int sd" "struct sockaddr *sa"
  20 .Sh DESCRIPTION
  21 .Fn bindresvport
  22 and
  23 .Fn bindresvport_sa
  24 are used to bind a socket descriptor to a reserved privileged
  25 .Tn IP
  26 port, that is, a
  27 port number in the range 0-1023.
  28 The routine returns 0 if it is successful,
  29 otherwise -1 is returned and
  30 .Va errno
  31 set to reflect the cause of the error.
  32 .Pp
  33 If
  34 .Fa sin
  35 is a pointer to a
  36 .Ft "struct sockaddr_in"
  37 then the appropriate fields in the structure should be defined.
  38 Note that
  39 .Fa sin-\*[Gt]sin_family
  40 must be initialized to the address family of the socket, passed by
  41 .Fa sd .
  42 If
  43 .Fa sin-\*[Gt]sin_port
  44 is
  45 .Sq 0
  46 then a port (in the range 600-1023) will be
  47 chosen, and if
  48 .Xr bind 2
  49 is successful, the
  50 .Fa sin-\*[Gt]sin_port
  51 will be updated to contain the allocated port.
  52 .Pp
  53 If
  54 .Fa sin
  55 is the
  56 .Dv NULL
  57 pointer,
  58 a port will be allocated (as above).
  59 However, there is no way for
  60 .Fn bindresvport
  61 to return the allocated port in this case.
  62 .Xr getsockname 2
  63 can be used to determine the assigned port.
  64 .Pp
  65 Only root can bind to a privileged port; this call will fail for any
  66 other users.
  67 .Pp
  68 Function prototype of
  69 .Fn bindresvport
  70 is biased to
  71 .Dv AF_INET
  72 socket.
  73 .Fn bindresvport_sa
  74 acts exactly the same, with more neutral function prototype.
  75 Note that both functions behave exactly the same, and
  76 both support
  77 .Dv AF_INET6
  78 sockets as well as
  79 .Dv AF_INET
  80 sockets.
  81 .Sh RETURN VALUES
  82 If the bind is successful, a 0 value is returned.
  83 A return value of -1 indicates an error, which is
  84 further specified in the global
  85 .Va errno .
  86 .Sh ERRORS
  87 .Bl -tag -width Er
  88 .It Bq Er EPFNOSUPPORT
  89 If second argument was supplied,
  90 and address family did not match between arguments.
  91 .El
  92 .Pp
  93 .Fn bindresvport
  94 may also fail and set
  95 .Va errno
  96 for any of the errors specified for the calls
  97 .Xr bind 2 ,
  98 .Xr getsockopt 2 ,
  99 or
 100 .Xr setsockopt 2 .
 101 .Sh SEE ALSO
 102 .Xr bind 2 ,
 103 .Xr getsockname 2 ,
 104 .Xr getsockopt 2 ,
 105 .Xr setsockopt 2 ,
 106 .Xr ip 4