bindresvport() does not automatically select another port if the

specified one is in use (closes PR 3192).
While I am here, reorganize and clean up much of the wording.
This now reads like a native speaker of English wrote it.

1 files changed, 34 insertions, 30 deletions

diff --git a/lib/libc/rpc/bindresvport.3 b/lib/libc/rpc/bindresvport.3
index eadf5cd189b..7b7f17b3184 100644
--- a/lib/libc/rpc/bindresvport.3
+++ b/lib/libc/rpc/bindresvport.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: bindresvport.3,v 1.19 2003/02/18 07:47:00 jmc Exp $
+.\"	$OpenBSD: bindresvport.3,v 1.20 2003/04/11 00:00:04 millert 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
@@ -42,52 +42,56 @@
 .Ft int
 .Fn bindresvport_sa "int sd" "struct sockaddr *sa"
 .Sh DESCRIPTION
+The
 .Fn bindresvport
 and
 .Fn bindresvport_sa
-are used to bind a socket descriptor to a privileged
+functions are used to bind a socket descriptor to a privileged
 .Tn IP
 port, that is, a port number in the range 0-1023.
+The
+.Fn bindresvport
+function operates solely on
+.Dv AF_INET
+sockets, whereas the
+.Fn bindresvport_sa
+function is capable of binding both
+.Dv AF_INET
+and
+.Dv AF_INET6
+sockets.
+.Pp
+Only the superuser may bind to a privileged port;
+these functions will fail for any other user.
+.Pp
 .Fa sd
-is a socket descriptor that was returned by a call to
+should be 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
+If
 .Va sin
-is not null,
+is not the NULL pointer,
 .Va sin->sin_family
-must be initialized to the address family of the socket, passed by
+must be initialized to the address family of the socket
 .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.
+will attempt to use the specified port.
+Otherwise, a free port in the range 600-1023 will be chosen and,
+if the
+.Xr bind 2
+succeeds,
+.Va sin->sin_port
+will be updated with the port that was assigned.
 .Pp
-Function prototype of
+If
+.Va sin
+is the NULL pointer, a free port in the range 600-1023 will be chosen
+(as above), but in this case there is no way for
 .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.
+to communicate to the caller which port was assigned.
 .Sh RETURN VALUES
 .Fn bindresvport
 returns 0 if it is successful, otherwise \-1 is returned and