.\"	$OpenBSD: bindresvport.3,v 1.19 2003/02/18 07:47:00 jmc Exp $
.\"
.\" Sun RPC is a product of Sun Microsystems, Inc. and is provided for
.\" unrestricted use provided that this legend is included on all tape
.\" media and as a part of the software program in whole or part.  Users
.\" may copy or modify Sun RPC without charge, but are not authorized
.\" to license or distribute it to anyone else except as part of a product or
.\" program developed by the user.
.\"
.\" SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
.\" WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
.\"
.\" Sun RPC is provided with no support and without any obligation on the
.\" part of Sun Microsystems, Inc. to assist in its use, correction,
.\" modification or enhancement.
.\"
.\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
.\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
.\" OR ANY PART THEREOF.
.\"
.\" In no event will Sun Microsystems, Inc. be liable for any lost revenue
.\" or profits or other special, indirect and consequential damages, even if
.\" Sun has been advised of the possibility of such damages.
.\"
.\" Sun Microsystems, Inc.
.\" 2550 Garcia Avenue
.\" Mountain View, California  94043
.\" 
.Dd August 9, 1997
.Dt BINDRESVPORT 3
.Os
.Sh NAME
.Nm bindresvport ,
.Nm bindresvport_sa
.Nd bind a socket to a privileged IP port
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <netinet/in.h>
.Ft int
.Fn bindresvport "int sd" "struct sockaddr_in *sin"
.Ft int
.Fn bindresvport_sa "int sd" "struct sockaddr *sa"
.Sh DESCRIPTION
.Fn bindresvport
and
.Fn bindresvport_sa
are used to bind a socket descriptor to a privileged
.Tn IP
port, that is, a port number in the range 0-1023.
.Fa sd
is a socket descriptor that was returned by a call to
.Xr socket 2 .
.Pp
Only root can bind to a privileged port; this call will fail for any
other users.
.Pp
When
.Va sin
is not null,
.Va sin->sin_family
must be initialized to the address family of the socket, passed by
.Va sd .
If the value of
.Va sin->sin_port
is non-zero,
.Fn bindresvport
attempts to use the specified port.
If that fails, it
chooses another privileged port number automatically.
.Pp
It is legal to pass null pointer to
.Va sin .
In this case, the caller cannot get the port number
.Fn bindresvport
has picked.
.Pp
Function prototype of
.Fn bindresvport
is biased to
.Dv AF_INET
socket.
.Fn bindresvport_sa
acts exactly the same, with more neutral function prototype.
Note that both functions behave exactly the same, and
both support
.Dv AF_INET6
sockets as well as
.Dv AF_INET
sockets.
.Sh RETURN VALUES
.Fn bindresvport
returns 0 if it is successful, otherwise \-1 is returned and
.Va errno
set to reflect the cause of the error.
.Sh ERRORS
The
.Fn bindresvport
function fails if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa sd
is not a valid descriptor.
.It Bq Er ENOTSOCK
.Fa sd
is not a socket.
.It Bq Er EADDRNOTAVAIL
The specified address is not available from the local machine.
.It Bq Er EADDRINUSE
The specified address is already in use.
.It Bq Er EINVAL
The socket is already bound to an address.
.It Bq Er EINVAL
The family of the socket and that requested in
.Va sa->sa_family
are not equivalent.
.It Bq Er EACCES
The requested address is protected, and the current user
has inadequate permission to access it.
.It Bq Er EFAULT
The
.Fa name
parameter is not in a valid part of the user
address space.
.It Bq Er ENOBUFS
Insufficient resources were available in the system
to perform the operation.
.It Bq Er EPFNOSUPPORT
The protocol family has not been configured into the
system, no implementation for it exists,
or address family did not match between arguments.
.El
.Sh SEE ALSO
.Xr bind 2 ,
.Xr socket 2 ,
.Xr rresvport 3 ,
.Xr rresvport_af 3