lib/libc/rpc/bindresvport.3

   1 .\" @(#)bindresvport.3n 2.2 88/08/02 4.0 RPCSRC; from 1.7 88/03/14 SMI
   2 .\" $FreeBSD: src/lib/libc/rpc/bindresvport.3,v 1.10.2.2 2001/12/14 18:33:56 ru Exp $
   3 .\"
   4 .Dd January 27, 2000
   5 .Dt BINDRESVPORT 3
   6 .Os
   7 .Sh NAME
   8 .Nm bindresvport ,
   9 .Nm bindresvport_sa
  10 .Nd bind a socket to a privileged IP port
  11 .Sh SYNOPSIS
  12 .In rpc/rpc.h
  13 .Ft int
  14 .Fn bindresvport "int sd" "struct sockaddr_in *sin"
  15 .Ft int
  16 .Fn bindresvport_sa "int sd" "struct sockaddr *sa"
  17 .Sh DESCRIPTION
  18 .Fn bindresvport
  19 and
  20 .Fn bindresvport_sa
  21 are used to bind a socket descriptor to a privileged
  22 .Tn IP
  23 port, that is, a
  24 port number in the range 0-1023.
  25 .Pp
  26 Only root can bind to a privileged port; this call will fail for any
  27 other users.
  28 .Pp
  29 When
  30 .Va sin
  31 is not null,
  32 .Va sin->sin_family
  33 must be initialized to the address family of the socket, passed by
  34 .Va sd .
  35 If the value of sin->sin_port is non-zero
  36 .Fn bindresvport
  37 will attempt to use that specific port.  If it fails, it chooses another
  38 privileged port automatically.
  39 .Pp
  40 It is legal to pass null pointer to
  41 .Va sin .
  42 In this case, the caller cannot get the port number
  43 .Fn bindresvport
  44 has picked.
  45 .Pp
  46 Function prototype of
  47 .Fn bindresvport
  48 is biased to
  49 .Dv AF_INET
  50 socket.
  51 .Fn bindresvport_sa
  52 acts exactly the same, with more neutral function prototype.
  53 Note that both functions behave exactly the same, and
  54 both support
  55 .Dv AF_INET6
  56 sockets as well as
  57 .Dv AF_INET
  58 sockets.
  59 .Sh RETURN VALUES
  60 .Fn bindresvport
  61 and
  62 .Fn bindresvport_sa
  63 return 0 if they are successful, otherwise \-1 is returned and
  64 .Va errno
  65 set to reflect the cause of the error.
  66 .Sh ERRORS
  67 The
  68 .Fn bindresvport
  69 and
  70 .Fn bindresvport_sa
  71 functions fail if:
  72 .Bl -tag -width Er
  73 .It Bq Er EBADF
  74 .Fa sd
  75 is not a valid descriptor.
  76 .It Bq Er ENOTSOCK
  77 .Fa sd
  78 is not a socket.
  79 .It Bq Er EADDRNOTAVAIL
  80 The specified address is not available from the local machine.
  81 .It Bq Er EADDRINUSE
  82 The specified address is already in use.
  83 .It Bq Er EINVAL
  84 The socket is already bound to an address,
  85 or the socket family and the family of specified address mismatch.
  86 .It Bq Er EACCES
  87 The requested address is protected, and the current user
  88 has inadequate permission to access it.
  89 .It Bq Er EFAULT
  90 The
  91 .Fa name
  92 parameter is not in a valid part of the user
  93 address space.
  94 .It Bq Er ENOBUFS
  95 Insufficient resources were available in the system
  96 to perform the operation.
  97 .It Bq Er EPFNOSUPPORT
  98 The protocol family has not been configured into the
  99 system, no implementation for it exists,
 100 or address family did not match between arguments.
 101 .El
 102 .Sh "SEE ALSO"
 103 .Xr bind 2 ,
 104 .Xr socket 2 ,
 105 .Xr rresvport 3 ,
 106 .Xr rresvport_af 3