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