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