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: src/lib/libc/rpc/bindresvport.3,v 1.15 2002/12/18 12:45:10 ru Exp $
   4 .\" $DragonFly: src/lib/libc/rpc/bindresvport.3,v 1.3 2007/08/18 20:48:47 swildner Exp $
   5 .\"
   6 .Dd January 27, 2000
   7 .Dt BINDRESVPORT 3
   8 .Os
   9 .Sh NAME
  10 .Nm bindresvport ,
  11 .Nm bindresvport_sa
  12 .Nd bind a socket to a privileged IP port
  13 .Sh LIBRARY
  14 .Lb libc
  15 .Sh SYNOPSIS
  16 .In sys/types.h
  17 .In rpc/rpc.h
  18 .Ft int
  19 .Fn bindresvport "int sd" "struct sockaddr_in *sin"
  20 .Ft int
  21 .Fn bindresvport_sa "int sd" "struct sockaddr *sa"
  22 .Sh DESCRIPTION
  23 The
  24 .Fn bindresvport
  25 and
  26 .Fn bindresvport_sa
  27 functions
  28 are used to bind a socket descriptor to a privileged
  29 .Tn IP
  30 port, that is, a
  31 port number in the range 0-1023.
  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->sin_family
  40 must be initialized to the address family of the socket, passed by
  41 .Fa sd .
  42 If
  43 .Fa sin->sin_port
  44 is
  45 .Sq 0
  46 then an anonymous port (in the range 600-1023) will be
  47 chosen, and if
  48 .Xr bind 2
  49 is successful, the
  50 .Fa sin->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 an anonymous 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 .Pp
  63 Only root can bind to a privileged port; this call will fail for any
  64 other users.
  65 .Pp
  66 Function prototype of
  67 .Fn bindresvport
  68 is biased to
  69 .Dv AF_INET
  70 socket.
  71 The
  72 .Fn bindresvport_sa
  73 function
  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 .Rv -std bindresvport
  83 .Sh ERRORS
  84 .Bl -tag -width Er
  85 .It Bq Er EPFNOSUPPORT
  86 If second argument was supplied,
  87 and address family did not match between arguments.
  88 .El
  89 .Pp
  90 The
  91 .Fn bindresvport
  92 function
  93 may also fail and set
  94 .Va errno
  95 for any of the errors specified for the calls
  96 .Xr bind 2 ,
  97 .Xr getsockopt 2 ,
  98 or
  99 .Xr setsockopt 2 .
 100 .Sh SEE ALSO
 101 .Xr bind 2 ,
 102 .Xr getsockopt 2 ,
 103 .Xr setsockopt 2 ,
 104 .Xr ip 4