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 2000/01/27 02:55:01 bde Exp $ |
---|
3 | .\" |
---|
4 | .Dd January 27, 2000 |
---|
5 | .Dt BINDRESVPORT 3 |
---|
6 | .Os |
---|
7 | .Sh NAME |
---|
8 | .Nm bindresvport , |
---|
9 | .Nm bindresvport_sa |
---|
10 | .Ndbind a socket to a privileged IP port |
---|
11 | .Sh SYNOPSIS |
---|
12 | .Fd #include <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 |
---|