From e6b5cd8f8a80b3b494b1a7040108e0824a5c0f9e Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Mon, 21 May 2007 11:00:08 +0000
Subject: [PATCH] Rewrite and substantial additional text.

---
 man3/bindresvport.3 | 53 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 48 insertions(+), 5 deletions(-)

diff --git a/man3/bindresvport.3 b/man3/bindresvport.3
index e2a8d8097..bb6a2f3cf 100644
--- a/man3/bindresvport.3
+++ b/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)