xref: /dragonfly/lib/libc/rpc/bindresvport.3 (revision f746689a) 
1.\" @(#)bindresvport.3n	2.2 88/08/02 4.0 RPCSRC; from 1.7 88/03/14 SMI
2.\" $NetBSD: bindresvport.3,v 1.8 2000/07/05 15:45:33 msaitoh Exp $
3.\" $FreeBSD: src/lib/libc/rpc/bindresvport.3,v 1.15 2002/12/18 12:45:10 ru Exp $
4.\" $DragonFly: src/lib/libc/rpc/bindresvport.3,v 1.3 2007/08/18 20:48:47 swildner Exp $
5.\"
6.Dd January 27, 2000
7.Dt BINDRESVPORT 3
8.Os
9.Sh NAME
10.Nm bindresvport ,
11.Nm bindresvport_sa
12.Nd bind a socket to a privileged IP port
13.Sh LIBRARY
14.Lb libc
15.Sh SYNOPSIS
16.In sys/types.h
17.In rpc/rpc.h
18.Ft int
19.Fn bindresvport "int sd" "struct sockaddr_in *sin"
20.Ft int
21.Fn bindresvport_sa "int sd" "struct sockaddr *sa"
22.Sh DESCRIPTION
23The
24.Fn bindresvport
25and
26.Fn bindresvport_sa
27functions
28are used to bind a socket descriptor to a privileged
29.Tn IP
30port, that is, a
31port number in the range 0-1023.
32.Pp
33If
34.Fa sin
35is a pointer to a
36.Ft "struct sockaddr_in"
37then the appropriate fields in the structure should be defined.
38Note that
39.Fa sin->sin_family
40must be initialized to the address family of the socket, passed by
41.Fa sd .
42If
43.Fa sin->sin_port
44is
45.Sq 0
46then an anonymous port (in the range 600-1023) will be
47chosen, and if
48.Xr bind 2
49is successful, the
50.Fa sin->sin_port
51will be updated to contain the allocated port.
52.Pp
53If
54.Fa sin
55is the
56.Dv NULL
57pointer,
58an anonymous port will be allocated (as above).
59However, there is no way for
60.Fn bindresvport
61to return the allocated port in this case.
62.Pp
63Only root can bind to a privileged port; this call will fail for any
64other users.
65.Pp
66Function prototype of
67.Fn bindresvport
68is biased to
69.Dv AF_INET
70socket.
71The
72.Fn bindresvport_sa
73function
74acts exactly the same, with more neutral function prototype.
75Note that both functions behave exactly the same, and
76both support
77.Dv AF_INET6
78sockets as well as
79.Dv AF_INET
80sockets.
81.Sh RETURN VALUES
82.Rv -std bindresvport
83.Sh ERRORS
84.Bl -tag -width Er
85.It Bq Er EPFNOSUPPORT
86If second argument was supplied,
87and address family did not match between arguments.
88.El
89.Pp
90The
91.Fn bindresvport
92function
93may also fail and set
94.Va errno
95for any of the errors specified for the calls
96.Xr bind 2 ,
97.Xr getsockopt 2 ,
98or
99.Xr setsockopt 2 .
100.Sh SEE ALSO
101.Xr bind 2 ,
102.Xr getsockopt 2 ,
103.Xr setsockopt 2 ,
104.Xr ip 4
105