1.\" $OpenBSD: bindresvport.3,v 1.25 2013/06/05 03:39:23 tedu Exp $ 2.\" 3.\" Copyright (c) 2010, Oracle America, Inc. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions are 7.\" met: 8.\" 9.\" * Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" * Redistributions in binary form must reproduce the above 12.\" copyright notice, this list of conditions and the following 13.\" disclaimer in the documentation and/or other materials 14.\" provided with the distribution. 15.\" * Neither the name of the "Oracle America, Inc." nor the names of its 16.\" contributors may be used to endorse or promote products derived 17.\" from this software without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 22.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 23.\" COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 24.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 26.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd $Mdocdate: June 5 2013 $ 33.Dt BINDRESVPORT 3 34.Os 35.Sh NAME 36.Nm bindresvport , 37.Nm bindresvport_sa 38.Nd bind a socket to a privileged IP port 39.Sh SYNOPSIS 40.In sys/types.h 41.In netinet/in.h 42.Ft int 43.Fn bindresvport "int sd" "struct sockaddr_in *sin" 44.Ft int 45.Fn bindresvport_sa "int sd" "struct sockaddr *sa" 46.Sh DESCRIPTION 47The 48.Fn bindresvport 49and 50.Fn bindresvport_sa 51functions are used to bind a socket descriptor to a privileged IP 52port, that is, a port number in the range 0-1023. 53The 54.Fn bindresvport 55function operates solely on 56.Dv AF_INET 57sockets, whereas the 58.Fn bindresvport_sa 59function is capable of binding both 60.Dv AF_INET 61and 62.Dv AF_INET6 63sockets. 64.Pp 65Only the superuser may bind to a privileged port; 66these functions will fail for any other user. 67.Pp 68.Fa sd 69should be a socket descriptor that was returned by a call to 70.Xr socket 2 . 71.Pp 72If 73.Va sin 74is not the NULL pointer, 75.Va sin->sin_family 76must be initialized to the address family of the socket 77.Va sd . 78If the value of 79.Va sin->sin_port 80is non-zero, 81.Fn bindresvport 82will attempt to use the specified port. 83Otherwise, a free port in the range 600-1023 will be chosen and, 84if the 85.Xr bind 2 86succeeds, 87.Va sin->sin_port 88will be updated with the port that was assigned. 89.Pp 90If 91.Va sin 92is the NULL pointer, a free port in the range 600-1023 will be chosen 93(as above), but in this case there is no way for 94.Fn bindresvport 95to communicate to the caller which port was assigned. 96.Sh RETURN VALUES 97.Fn bindresvport 98returns 0 if it is successful, otherwise \-1 is returned and 99.Va errno 100set to reflect the cause of the error. 101.Sh ERRORS 102The 103.Fn bindresvport 104function fails if: 105.Bl -tag -width Er 106.It Bq Er EBADF 107.Fa sd 108is not a valid descriptor. 109.It Bq Er ENOTSOCK 110.Fa sd 111is not a socket. 112.It Bq Er EADDRNOTAVAIL 113The specified address is not available from the local machine. 114.It Bq Er EADDRINUSE 115The specified address is already in use. 116.It Bq Er EINVAL 117The socket is already bound to an address. 118.It Bq Er EINVAL 119The family of the socket and that requested in 120.Va sa->sa_family 121are not equivalent. 122.It Bq Er EACCES 123The requested address is protected, and the current user 124has inadequate permission to access it. 125.It Bq Er EFAULT 126The 127.Fa name 128parameter is not in a valid part of the user 129address space. 130.It Bq Er ENOBUFS 131Insufficient resources were available in the system 132to perform the operation. 133.It Bq Er EPFNOSUPPORT 134The protocol family has not been configured into the 135system, no implementation for it exists, 136or address family did not match between arguments. 137.El 138.Sh SEE ALSO 139.Xr bind 2 , 140.Xr socket 2 , 141.Xr rresvport 3 , 142.Xr rresvport_af 3 143