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