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