--- /dev/null	Tue Aug 12 07:52:14 2014
+++ new/usr/src/man/man3nsl/gethostent.3nsl	Tue Aug 12 07:52:14 2014
@@ -0,0 +1,288 @@
+.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
+.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved.
+.\" Copyright 1989 AT&T.
+.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved
+.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
+.\" http://www.opengroup.org/bookstore/.
+.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
+.\"  This notice shall appear on any product containing this material.
+.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
+.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
+.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
+.Dd Jul 22, 2014
+.Dt GETHOSTBYNAME 3NSL
+.Os
+.Sh NAME
+.Nm gethostent, gethostent_r, sethostent, endhostent
+.Nd enumerate network host entries
+.Sh SYNOPSIS
+.Ic cc
+.Op Ar flag No Ns ...
+.Ar file No Ns ...
+.Fl lnsl
+.Op Ar library No Ns ...
+.Lp
+.In netdb.h
+.Ft "struct hostent *"
+.Fn gethostent "void"
+.Ft "struct hostent *"
+.Fo gethostent_r
+.Fa "struct hostent *result"
+.Fa "char *buffer"
+.Fa "int buflen"
+.Fa "int *h_errnop"
+.Fc
+.Ft int
+.Fn sethostent "int stayopen"
+.Ft int
+.Fn endhostent void
+.Sh DESCRIPTION
+These functions are used to enumerate entries in the network hosts database.
+An entries can come
+from any of the sources for
+.Sy hosts
+specified in the
+.Pa /etc/nsswitch.conf
+file. See
+.Xr nsswitch.conf 4 .
+.Lp
+All addresses are returned in network order. In order to interpret the
+addresses,
+.Xr byteorder 3SOCKET
+must be used for byte order conversion.
+.Lp
+The
+.Fn sethostent
+function sets or resets the enumeration to the beginning
+of the set of host entries. This function should be called before the first
+call to
+.Fn gethostent .
+If the
+.Fa stayopen
+flag is non-zero, the system can keep allocated resources
+such as open file descriptors until a subsequent call to
+.Fn endhostent .
+.Lp
+Successive calls to the
+.Fn gethostent
+function return either successive
+entries or
+.Dv NULL ,
+indicating the end of the enumeration.
+.Lp
+The
+.Fn endhostent()
+function can be called to indicate that the caller
+expects to do no further host entry retrieval operations; the system can then
+deallocate resources it was using. It is still allowed, but possibly less
+efficient, for the process to call more host retrieval functions after calling
+.Fn endhostent .
+.Lp
+The
+.Fn gethostent
+function uses static storage that is reused in each call, making this
+function unsafe for use in multithreaded applications.
+.Lp
+The
+.Fn gethostent_r
+function performs the same function as
+.Fn gethostent, but provides a reentrant interface.
+It uses a buffer supplied by the caller to store returned results and
+is safe for use in both single-threaded and multithreaded applications.
+.Lp
+The
+.Fn gethostent_r
+function takes the same parameters as
+.Fn gethostent ,
+as well as the following additional parameters. The parameter
+.Fa result
+must be a pointer to a
+.Vt "struct hostent"
+structure allocated by the caller. On successful completion, the function
+returns the host entry in
+this structure. The parameter
+.Fa buffer
+must be a pointer to a buffer
+supplied by the caller. This buffer is used as storage space for the host data.
+All of the pointers within the returned
+.Vt "struct hostent"
+point to data stored within this buffer. See the
+.Sx RETURN VALUES
+section for more
+information. The buffer must be large enough to hold all of the data associated
+with the host entry. The parameter
+.Fa buflen
+should give the size in bytes
+of the buffer indicated by
+.Fa buffer . The parameter
+.Fa h_errnop
+should be
+a pointer to an integer. An integer error status value is stored there on
+certain error conditions. See the
+.Sx ERRORS
+section for more information.
+.Sh RETURN VALUES
+The
+.Fn gethostent
+and
+.Fn gethostent_r
+functions each return a pointer
+to a
+.Vt "struct hostent"
+if they successfully enumerate an entry; otherwise they return
+.Dv NULL ,
+indicating the end of the enumeration.  See
+.Xr gethostbyname 3NSL
+for a descriptin of the
+.Vt "struct hostent"
+structure.
+.Lp
+The
+.Fn gethostent
+function uses static storage, so results from from one call may be overwritten
+by subsequent calls it.
+.Lp
+When the pointer returned by
+.Fn gethostent_r
+is not
+.Dv NULL , it is
+always equal to the
+.Fa result
+pointer that was supplied by the caller.
+.Lp
+The
+.Fn sethostent
+and
+.Fn endhostent
+functions return 0 on success.
+.Sh FILES
+.Bl -tag -width "/etc/nsswitch.conf"
+.It Pa /etc/hosts
+hosts file that associates the names of hosts with their Internet Protocol (IP)
+addresses
+.It Pa /etc/nsswitch.conf
+configuration file for the name service switch
+.El
+.Sh ERRORS
+The
+.Fn gethostent_r
+function will return
+.Dv NULL
+and set
+.Va errno
+to
+.Er ERANGE
+if the length of the buffer supplied by caller is not large enough to store the
+result.  It may also store one of the following
+.Va h_errno
+values into the location pointed by
+.Fa h_errnop .  On error, the
+.Fn gethostent
+function will set the global
+.Va h_errno
+value to one of these values:
+.Dv HOST_NOT_FOUND ,
+.Dv TRY_AGAIN ,
+.Dv NO_RECOVERY ,
+.Dv NO_DATA ,
+.Dv NO_ADDRESS ,
+or
+.Dv NETDB_INTERNAL .
+.Sh INTERFACE STABILITY
+The
+.Fn gethostent ,
+.Fn sethostent ,
+and
+.Fn endhostent
+functions are
+.Sy Standard .
+The
+.Fn gethostent_r
+function is
+.Sy Obsolete Uncommitted .
+.Sh MT-LEVEL
+The
+.Fn gethostent
+function is
+.Sy Unsafe .
+.Lp
+The
+.Fn gethostent_r ,
+.Fn sethostent ,
+and
+.Fn endhostent
+functions are
+.Sy Safe with Exceptions .
+For enumeration in multithreaded applications, the position within the
+enumeration is a process-wide property shared by all threads.
+If multiple threads interleave
+calls to these functions,
+the threads will enumerate disjoint subsets of the host database.
+.Sh SEE ALSO
+.Xr byteorder 3SOCKET ,
+.Xr gethostbyname 3NSL ,
+.Xr netdb.h 3HEAD ,
+.Xr hosts 4 ,
+.Xr nss 4 ,
+.Xr nsswitch.conf 4 ,
+.Xr standards 5
+.Sh NOTES
+The
+.Fn gethostent_r
+function is provided as an
+.Sy Uncommitted
+interface, and is subject to removal or change in a subsequent release.
+.Lp
+The
+.Fn gethostent
+and
+.Fn gethostent_r
+functions must always return the
+.Em canonical name
+in the
+.Fa h_name
+field. This name, by definition, is
+the well-known and official hostname shared between all aliases and all
+addresses. The underlying source that satisfies the request determines the
+mapping of the input name or address into the set of names and addresses in
+.Fa hostent .
+Different sources might do that in different ways. If there is
+more than one alias and more than one address in
+.Fa hostent ,
+no pairing is implied between them.
+.Lp
+The system attempts to put those addresses that are on the same subnet as the
+caller before addresses that are on different subnets. However, if address
+sorting is disabled by setting
+.Sy SORT_ADDRS
+to
+.Sy FALSE
+in the
+.Pa /etc/default/nss
+file, the system does not put the local subnet addresses
+first. See
+.Xr nss 4
+for more information.
+.Lp
+Use of these enumeration functions
+is discouraged; enumeration might not be supported for all database sources.
+The semantics of enumeration are discussed further in
+.Xr nsswitch.conf 4 .
+.Lp
+The current implementations of these functions only return addresses
+for the Internet address family
+.Po type Dv AF_INET Pc .
+See
+.Xr inet 4
+for more information.
+.Sh STANDARDS
+The
+.Fn gethostent ,
+.Fn sethostent ,
+and
+.Fn endhostent
+functions were introduced in
+.Bx 4.2
+and standardized in
+.St -xns5.2 and
+.St -p1003.1-2001 .
