Rewrite and substantial additional text.

man3/bindresvport.3

@@ -1,7 +1,12 @@
-.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
+.\" This page was initially taken from the 4.4BSD-Lite CDROM (BSD license)
+.\" with substantial updates 
+.\" Copyright (C) 2007, Michael Kerrisk <mtk-manpages@gmx.net>
 .\"
 .\" @(#)bindresvport.3n	2.2 88/08/02 4.0 RPCSRC; from 1.7 88/03/14 SMI
-.TH BINDRESVPORT 3  1987-11-22 "" "Linux Programmer's Manual"
+.\"
+.\" 2007-05-31, mtk: Rewrite and substantial additional text.
+.\"
+.TH BINDRESVPORT 3  2007-05-31 "" "Linux Programmer's Manual"
 .SH NAME
 bindresvport \- bind a socket to a privileged IP port
 .SH SYNOPSIS
@@ -18,10 +23,48 @@ is used to bind a socket descriptor to a privileged
 .SM IP
 port, that is, a
 port number in the range 0-1023.
-The routine returns 0 if it is successful,
-otherwise \-1 is returned and
+
+If
+.I in\->sin_port
+is 0 then an anonymous port in the range 600 to 1023
+be chosen.
+If the
+.BR bind (2)
+perfomed by 
+.BR bindresvport ()
+is successful, then
+.I sin\->sin_port
+returns the port number actually allocated.
+
+.I sin
+can be NULL, in which case
+.I sin\->sin_family
+is implicitly taken to be
+.BR AF_INET ,
+and an anonymous port is allocated (as above).  
+However, in this case, 
+.BR bindresvport ()
+has no way to return the port number actually allocated.
+.SH RETURN VALUE
+.BR bindresvport ()
+returns 0 if it is successful, otherwise \-1 is returned and
 .I errno
-set to reflect the cause of the error.
+set to indicate the cause of the error.
+.SH ERRORS
+.BR bindresvport ()
+can fail for any of the same reasons as
+.BR bid (2).
+.SH NOTES
 .LP
 Only root can bind to a privileged port; this call will fail for any
 other users.
+In addition, the following error may occur:
+.TP
+.B EPFNOSUPPORT
+.I sin
+is not NULL and
+.I sin\->sin_family
+is not 
+.BR AF_INET .
+.SH SEE ALSO
+.BR bind (2)