man3/bindresvport.3

   1 '\" t
   2 .\" Copyright (C) 2007, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" and Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk
   4 .\"     <mtk.manpages@gmail.com>
   5 .\"
   6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   7 .\"
   8 .\" 2007-05-31, mtk: Rewrite and substantial additional text.
   9 .\" 2008-12-03, mtk: Rewrote some pieces and fixed some errors
  10 .\"
  11 .TH bindresvport 3 (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 bindresvport \- bind a socket to a privileged IP port
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <sys/types.h>
  20 .B #include <netinet/in.h>
  21 .PP
  22 .BI "int bindresvport(int " sockfd ", struct sockaddr_in *" sin );
  23 .fi
  24 .SH DESCRIPTION
  25 .BR bindresvport ()
  26 is used to bind the socket referred to by the
  27 file descriptor
  28 .I sockfd
  29 to a privileged anonymous IP port,
  30 that is, a port number arbitrarily selected from the range 512 to 1023.
  31 .\" glibc actually starts searching with a port # in the range 600 to 1023
  32 .PP
  33 If the
  34 .BR bind (2)
  35 performed by
  36 .BR bindresvport ()
  37 is successful, and
  38 .I sin
  39 is not NULL, then
  40 .I sin\->sin_port
  41 returns the port number actually allocated.
  42 .PP
  43 .I sin
  44 can be NULL, in which case
  45 .I sin\->sin_family
  46 is implicitly taken to be
  47 .BR AF_INET .
  48 However, in this case,
  49 .BR bindresvport ()
  50 has no way to return the port number actually allocated.
  51 (This information can later be obtained using
  52 .BR getsockname (2).)
  53 .SH RETURN VALUE
  54 .BR bindresvport ()
  55 returns 0 on success; otherwise \-1 is returned and
  56 .I errno
  57 is set to indicate the error.
  58 .SH ERRORS
  59 .BR bindresvport ()
  60 can fail for any of the same reasons as
  61 .BR bind (2).
  62 In addition, the following errors may occur:
  63 .TP
  64 .B EACCES
  65 The calling process was not privileged
  66 (on Linux: the calling process did not have the
  67 .B CAP_NET_BIND_SERVICE
  68 capability in the user namespace governing its network namespace).
  69 .TP
  70 .B EADDRINUSE
  71 All privileged ports are in use.
  72 .TP
  73 .BR EAFNOSUPPORT " (" EPFNOSUPPORT " in glibc 2.7 and earlier)"
  74 .I sin
  75 is not NULL and
  76 .I sin\->sin_family
  77 is not
  78 .BR AF_INET .
  79 .SH ATTRIBUTES
  80 For an explanation of the terms used in this section, see
  81 .BR attributes (7).
  82 .TS
  83 allbox;
  84 lb lb lbx
  85 l l l.
  86 Interface       Attribute       Value
  87 T{
  88 .na
  89 .nh
  90 .BR bindresvport ()
  91 T}      Thread safety   T{
  92 .na
  93 .nh
  94 glibc\ >=\ 2.17: MT-Safe;
  95 .\" commit f6da27e53695ad1cc0e2a9490358decbbfdff5e5
  96 glibc\ <\ 2.17: MT-Unsafe
  97 T}
  98 .TE
  99 .sp 1
 100 .PP
 101 The
 102 .BR bindresvport ()
 103 function uses a static variable that was not protected by a lock
 104 before glibc 2.17, rendering the function MT-Unsafe.
 105 .SH VERSIONS
 106 Present on the BSDs, Solaris, and many other systems.
 107 .SH NOTES
 108 Unlike some
 109 .BR bindresvport ()
 110 implementations,
 111 the glibc implementation ignores any value that the caller supplies in
 112 .IR sin\->sin_port .
 113 .SH STANDARDS
 114 BSD.
 115 .SH SEE ALSO
 116 .BR bind (2),
 117 .BR getsockname (2)