Stop talking about /etc/networks, which is no longer used,

and reference gethostby*(3) and /etc/hosts instead.
Say that setnetent(3), getnetent(3), and endnetent(3) now do nothing.
With feedback from guenther and significant help from deraadt@.

1 files changed, 38 insertions, 39 deletions

diff --git a/src/lib/libc/net/getnetent.3 b/src/lib/libc/net/getnetent.3
index f45526ec1d..0f4f74e364 100644
--- a/src/lib/libc/net/getnetent.3
+++ b/src/lib/libc/net/getnetent.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: getnetent.3,v 1.17 2017/11/28 18:10:59 schwarze Exp $
+.\"     $OpenBSD: getnetent.3,v 1.18 2018/04/28 15:37:43 schwarze Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
 .\"     The Regents of the University of California.  All rights reserved.
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 28 2017 $
+.Dd $Mdocdate: April 28 2018 $
 .Dt GETNETENT 3
 .Os
 .Sh NAME
@@ -51,13 +51,10 @@
 .Fn endnetent "void"
 .Sh DESCRIPTION
 The
-.Fn getnetent ,
-.Fn getnetbyname ,
+.Fn getnetbyname
 and
 .Fn getnetbyaddr
-functions each return a pointer to an object with the following structure
-containing the broken-out fields of a line in the network database,
-.Pa /etc/networks .
+functions return a pointer to an object with the following structure:
 .Bd -literal -offset indent
 struct  netent {
         char            *n_name;        /* official name of net */
@@ -74,59 +71,61 @@ The official name of the network.
 .It Fa n_aliases
 A null-terminated list of alternate names for the network.
 .It Fa n_addrtype
-The type of the network number returned; currently only
+The type of the network number returned; it is always
 .Dv AF_INET .
 .It Fa n_net
 The network number.
 Network numbers are returned in machine byte order.
 .El
 .Pp
-The
-.Fn getnetent
-function reads the next line of the file, opening the file if necessary.
-.Pp
-The
-.Fn setnetent
-function opens and rewinds the file.
-If the
-.Fa stayopen
-flag is non-zero,
-the net database will not be closed after each call to
-.Fn getnetbyname
-or
-.Fn getnetbyaddr .
+On
+.Ox ,
+these legacy functions perform a lookup in a similar fashion as
+.Xr gethostbyname 3
+and
+.Xr gethostbyaddr 3 ,
+respectively.
+On other systems, they may use a separate network database file,
+.Pa /etc/networks .
 .Pp
-The
-.Fn endnetent
-function closes the file.
+In contrast to
+.Xr gethostbyaddr 3 ,
+the
+.Fa net
+argument is expected in machine byte order.
 .Pp
 The
-.Fn getnetbyname
+.Fn setnetent ,
+.Fn getnetent ,
 and
-.Fn getnetbyaddr
-functions search the domain name server if the system is configured to use one.
-If the search fails, or no name server is configured, they sequentially
-search from the beginning of the file until a matching net name or
-net address and type is found, or until
-.Dv EOF
-is encountered.
-Network numbers are supplied in host order.
+.Fn endnetent
+functions are deprecated and no longer have any effect.
+They could be used in the past to iterate over entries in the former file
+.Pa /etc/networks .
 .Sh RETURN VALUES
 The
-.Fn getnetent ,
-.Fn getnetbyaddr ,
+.Fn getnetbyaddr
 and
 .Fn getnetbyname
 functions return
 .Dv NULL
 if the requested entry is not found.
+.Pp
+The
+.Fn getnetent
+function always returns
+.Dv NULL .
 .Sh FILES
-.Bl -tag -width /etc/networks -compact
-.It Pa /etc/networks
+.Bl -tag -width /etc/hosts -compact
+.It Pa /etc/hosts
+The local host and network name database.
 .El
 .Sh SEE ALSO
+.Xr getaddrinfo 3 ,
+.Xr gethostbyname 3 ,
+.Xr getnameinfo 3 ,
 .Xr resolver 3 ,
-.Xr networks 5
+.Xr hosts 5
 .Sh STANDARDS
 These functions conform to
 .St -p1003.1-2008 .