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