Print this page
Ensured various XPG7 stuff are declared properly in sys/stat.h (and cleanup)
New documentation for wcslen, wcsnlen, wcscasecmp (and friends), wcsdup.
Various other tweaks and markup improvements.
Finished obsoleting interfaces for XPG7.
*** 1,6 ****
! '\" te
.\" 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/.
--- 1,6 ----
! .\" 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/.
*** 7,255 ****
.\" 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]
! .TH GETHOSTBYNAME 3NSL "Sep 10, 2013"
! .SH NAME
! gethostbyname, gethostbyname_r, gethostbyaddr, gethostbyaddr_r, gethostent,
! gethostent_r, sethostent, endhostent \- get network host entry
! .SH SYNOPSIS
! .LP
! .nf
! \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR... ]
! #include <netdb.h>
!
! \fBstruct hostent *\fR\fBgethostbyname\fR(\fBconst char *\fR\fIname\fR);
! .fi
!
! .LP
! .nf
! \fBstruct hostent *\fR\fBgethostbyname_r\fR(\fBconst char *\fR\fIname\fR,
! \fBstruct hostent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR,
! \fBint *\fR\fIh_errnop\fR);
! .fi
!
! .LP
! .nf
! \fBstruct hostent *\fR\fBgethostbyaddr\fR(\fBconst char *\fR\fIaddr\fR, \fBint\fR \fIlen\fR,
! \fBint\fR \fItype\fR);
! .fi
!
! .LP
! .nf
! \fBstruct hostent *\fR\fBgethostbyaddr_r\fR(\fBconst char *\fR\fIaddr\fR, \fBint\fR \fIlength\fR,
! \fBint\fR \fItype\fR, \fBstruct hostent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR,
! \fBint\fR \fIbuflen\fR, \fBint *\fR\fIh_errnop\fR);
! .fi
!
! .LP
! .nf
! \fBstruct hostent *\fR\fBgethostent\fR(\fBvoid\fR);
! .fi
!
! .LP
! .nf
! \fBstruct hostent *\fR\fBgethostent_r\fR(\fBstruct hostent *\fR\fIresult\fR,
! \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR, \fBint *\fR\fIh_errnop\fR);
! .fi
!
! .LP
! .nf
! \fBint\fR \fBsethostent\fR(\fBint\fR \fIstayopen\fR);
! .fi
!
! .LP
! .nf
! \fBint\fR \fBendhostent\fR(\fBvoid\fR);
! .fi
!
! .SH DESCRIPTION
! .sp
! .LP
These functions are used to obtain entries describing hosts. An entry can come
! from any of the sources for \fBhosts\fR specified in the
! \fB/etc/nsswitch.conf\fR file. See \fBnsswitch.conf\fR(4). These functions have
! been superseded by \fBgetipnodebyname\fR(3SOCKET),
! \fBgetipnodebyaddr\fR(3SOCKET), and \fBgetaddrinfo\fR(3SOCKET), which provide
greater portability to applications when multithreading is performed or
technologies such as IPv6 are used. For example, the functions described in the
following cannot be used with applications targeted to work with IPv6.
! .sp
! .LP
! The \fBgethostbyname()\fR function searches for information for a host with the
! hostname specified by the character-string parameter \fIname\fR.
! .sp
! .LP
! The \fBgethostbyaddr()\fR function searches for information for a host with a
! given host address. The parameter \fBtype\fR specifies the family of the
address. This should be one of the address families defined in
! \fB<sys/socket.h>\fR\&. See the \fBNOTES\fR section for more information. Also
! see the \fBEXAMPLES\fR section for information on how to convert an Internet
! \fBIP\fR address notation that is separated by periods (.) into an \fIaddr\fR
! parameter. The parameter \fIlen\fR specifies the length of the buffer indicated
! by \fIaddr\fR.
! .sp
! .LP
All addresses are returned in network order. In order to interpret the
! addresses, \fBbyteorder\fR(3SOCKET) must be used for byte order conversion.
! .sp
! .LP
! The \fBsethostent()\fR, \fBgethostent()\fR, and \fBendhostent()\fR functions
! are used to enumerate host entries from the database.
! .sp
! .LP
! The \fBsethostent()\fR 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 \fBgethostent()\fR. Calls to \fBgethostbyname()\fR and
! \fBgethostbyaddr()\fR leave the enumeration position in an indeterminate state.
! If the \fIstayopen\fR flag is non-zero, the system can keep allocated resources
! such as open file descriptors until a subsequent call to \fBendhostent()\fR.
! .sp
! .LP
! Successive calls to the \fBgethostent()\fR function return either successive
! entries or \fINULL,\fR indicating the end of the enumeration.
! .sp
! .LP
! The \fBendhostent()\fR 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
! \fBendhostent()\fR.
! .SS "Reentrant Interfaces"
! .sp
! .LP
! The \fBgethostbyname()\fR, \fBgethostbyaddr()\fR, and \fBgethostent()\fR
functions use static storage that is reused in each call, making these
functions unsafe for use in multithreaded applications.
! .sp
! .LP
! The \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and \fBgethostent_r()\fR
functions provide reentrant interfaces for these operations.
! .sp
! .LP
Each reentrant interface performs the same operation as its non-reentrant
! counterpart, named by removing the \fB_r\fR suffix. The reentrant interfaces,
however, use buffers supplied by the caller to store returned results and the
interfaces are safe for use in both single-threaded and multithreaded
applications.
! .sp
! .LP
Each reentrant interface takes the same parameters as its non-reentrant
counterpart, as well as the following additional parameters. The parameter
! \fIresult\fR must be a pointer to a \fBstruct hostent\fR structure allocated by
the caller. On successful completion, the function returns the host entry in
! this structure. The parameter \fIbuffer\fR 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 \fBstruct hostent\fR \fIresult\fR point
! to data stored within this buffer. See the \fBRETURN VALUES\fR section for more
information. The buffer must be large enough to hold all of the data associated
! with the host entry. The parameter \fIbuflen\fR should give the size in bytes
! of the buffer indicated by \fIbuffer\fR. The parameter \fIh_errnop\fR should be
a pointer to an integer. An integer error status value is stored there on
! certain error conditions. See the \fBERRORS\fR section for more information.
! .sp
! .LP
! For enumeration in multithreaded applications, the position within the
! enumeration is a process-wide property shared by all threads. The
! \fBsethostent()\fR function can be used in a multithreaded application but
! resets the enumeration position for all threads. If multiple threads interleave
! calls to \fBgethostent_r()\fR, the threads will enumerate disjoint subsets of
! the host database.
! .sp
! .LP
! Like their non-reentrant counterparts, \fBgethostbyname_r()\fR and
! \fBgethostbyaddr_r()\fR leave the enumeration position in an indeterminate
! state.
! .SH RETURN VALUES
! .sp
! .LP
! Host entries are represented by the \fBstruct hostent\fR structure defined in
! \fB<netdb.h>\fR:
! .sp
! .in +2
! .nf
struct hostent {
char *h_name; /* canonical name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
};
! .fi
! .in -2
!
! .sp
! .LP
! See the \fBEXAMPLES\fR section for information about how to retrieve a ``.''
! separated Internet \fBIP\fR address string from the \fIh_addr_list\fR field of
! \fBstruct hostent\fR.
! .sp
! .LP
! The \fBgethostbyname()\fR, \fBgethostbyname_r()\fR, \fBgethostbyaddr()\fR, and
! \fBgethostbyaddr_r()\fR functions each return a pointer to a \fBstruct
! hostent\fR if they successfully locate the requested entry; otherwise they
! return \fINULL\fR.
! .sp
! .LP
! The \fBgethostent()\fR and \fBgethostent_r()\fR functions each return a pointer
! to a \fBstruct hostent\fR if they successfully enumerate an entry; otherwise
! they return \fINULL\fR, indicating the end of the enumeration.
! .sp
! .LP
! The \fBgethostbyname()\fR, \fBgethostbyaddr()\fR, and \fBgethostent()\fR
functions use static storage, so returned data must be copied before a
subsequent call to any of these functions if the data is to be saved.
! .sp
! .LP
! When the pointer returned by the reentrant functions \fBgethostbyname_r()\fR,
! \fBgethostbyaddr_r()\fR, and \fBgethostent_r()\fR is not \fINULL\fR, it is
! always equal to the \fIresult\fR pointer that was supplied by the caller.
! .sp
! .LP
! The \fBsethostent()\fR and \fBendhostent()\fR functions return \fB0\fR on
! success.
! .SH ERRORS
! .sp
! .LP
! The reentrant functions \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and
! \fBgethostent_r()\fR will return \fINULL\fR and set \fIerrno\fR to \fBERANGE\fR
! if the length of the buffer supplied by caller is not large enough to store the
! result. See \fBIntro\fR(2) for the proper usage and interpretation of
! \fBerrno\fR in multithreaded applications.
! .sp
! .LP
! The reentrant functions \fBgethostbyname_r()\fR and \fBgethostbyaddr_r()\fR set
! the integer pointed to by \fIh_errnop\fR to one of these values in case of
! error.
! .sp
! .LP
! On failures, the non-reentrant functions \fBgethostbyname()\fR and
! \fBgethostbyaddr()\fR set a global integer \fIh_errno\fR to indicate one of
! these error codes (defined in \fB<netdb.h>\fR): \fBHOST_NOT_FOUND\fR,
! \fBTRY_AGAIN\fR, \fBNO_RECOVERY\fR, \fBNO_DATA\fR, and \fBNO_ADDRESS\fR.
! .sp
! .LP
! If a resolver is provided with a malformed address, or if any other error
! occurs before \fBgethostbyname()\fR is resolved, then \fBgethostbyname()\fR
! returns an internal error with a value of \(mi1.
! .sp
! .LP
! The \fBgethostbyname()\fR function will set \fIh_errno\fR to
! \fBNETDB_INTERNAL\fR when it returns a \fINULL\fR value.
! .SH EXAMPLES
! .LP
! \fBExample 1 \fRUsing \fBgethostbyaddr()\fR
! .sp
! .LP
Here is a sample program that gets the canonical name, aliases, and ``.''
! separated Internet \fBIP\fR addresses for a given ``.'' separated \fBIP\fR
address:
!
! .sp
! .in +2
! .nf
#include <stdio.h>
#include <stdlib.h
#include <string.h>
#include <sys/types.h>
#include <sys/socket.h>
--- 7,226 ----
.\" 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 gethostbyname ,
! .Nm gethostbyname_r ,
! .Nm gethostbyaddr ,
! .Nm gethostbyaddr_r
! .Nd lookup network host entry
! .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 gethostbyname "const char *name"
! .Ft "struct hostent *"
! .Fo gethostbyname_r
! .Fa "const char *name"
! .Fa "struct hostent *result"
! .Fa "char *buffer"
! .Fa "int buflen"
! .Fa "int *h_errnop"
! .Fc
! .Ft "struct hostent *"
! .Fo gethostbyaddr
! .Fa "const char *addr"
! .Fa "socklen_t len"
! .Fa "int type"
! .Fc
! .Ft "struct hostent *"
! .Fo gethostbyaddr_r
! .Fa "const char *addr"
! .Fa "int length"
! .Fa "int type"
! .Fa "struct hostent *result"
! .Fa "char *buffer"
! .Fa "int buflen"
! .Fa "int *h_errnop"
! .Fc
! .Sh DESCRIPTION
These functions are used to obtain entries describing hosts. An entry can come
! from any of the sources for
! .Sy hosts
! specified in the
! .Pa /etc/nsswitch.conf
! file. See
! .Xr nsswitch.conf 4 .
! These functions have been superseded by
! .Xr getipnodebyname 3SOCKET ,
! .Xr getipnodebyaddr 3SOCKET ,
! and
! .Xr getaddrinfo 3SOCKET ,
! which provide
greater portability to applications when multithreading is performed or
technologies such as IPv6 are used. For example, the functions described in the
following cannot be used with applications targeted to work with IPv6.
! .Lp
! The
! .Fn gethostbyname
! function searches for information for a host with the
! hostname specified by the character-string parameter
! .Fa name .
! .Lp
! The
! .Fn gethostbyaddr
! function searches for information for a host with a
! given host address. The parameter
! .Fa type
! specifies the family of the
address. This should be one of the address families defined in
! .In sys/socket.h .
! See the
! .Sx NOTES
! section for more information. Also
! see the
! .Sx EXAMPLES
! section for information on how to convert an Internet
! Protocol address notation that is separated by periods (.) into an
! .Fa addr
! parameter. The parameter
! .Fa len
! specifies the length of the buffer indicated
! by
! .Fa addr .
! .Lp
All addresses are returned in network order. In order to interpret the
! addresses,
! .Xr byteorder 3SOCKET
! must be used for byte order conversion.
! .Ss "Reentrant Interfaces"
! The
! .Fn gethostbyname
! and
! .Fn gethostbyaddr
functions use static storage that is reused in each call, making these
functions unsafe for use in multithreaded applications.
! .Lp
! The
! .Fn gethostbyname_r
! and
! .Fn gethostbyaddr_r
functions provide reentrant interfaces for these operations.
! .Lp
Each reentrant interface performs the same operation as its non-reentrant
! counterpart, named by removing the
! .Sy _r
! suffix. The reentrant interfaces,
however, use buffers supplied by the caller to store returned results and the
interfaces are safe for use in both single-threaded and multithreaded
applications.
! .Lp
Each reentrant interface takes the same parameters as its non-reentrant
counterpart, 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
! Host entries are represented by the
! .Vt "struct hostent"
! structure defined in
! .In netdb.h :
! .Bd -literal -offset indent
struct hostent {
char *h_name; /* canonical name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
};
! .Ed
! .Lp
! See the
! .Sx EXAMPLES
! section for information about how to retrieve a
! .Sq \&.
! separated Internet Protocol address string from the
! .Fa h_addr_list
! field of
! .Vt "struct hostent" .
! .Lp
! The
! .Fn gethostbyname ,
! .Fn gethostbyname_r ,
! .Fn gethostbyaddr ,
! and
! .Fn gethostbyaddr_r
! functions each return a pointer to a
! .Vt "struct hostent"
! if they successfully locate the requested entry; otherwise they
! return
! .Dv NULL .
! .Lp
! The
! .Fn gethostbyname
! and
! .Fn gethostbyaddr
functions use static storage, so returned data must be copied before a
subsequent call to any of these functions if the data is to be saved.
! .Lp
! When the pointer returned by the reentrant functions
! .Fn gethostbyname_r
! and
! .Fn gethostbyaddr_r
! is not
! .Dv NULL ,
! it is always equal to the
! .Fa result
! pointer that was supplied by the caller.
! .Sh FILES
! .Bl -tag -width Pa
! .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 EXAMPLES
! .Ss Example 1 Using gethostbyaddr()
Here is a sample program that gets the canonical name, aliases, and ``.''
! separated Internet Protocol addresses for a given ``.'' separated IP
address:
! .Bd -literal -offset indent
#include <stdio.h>
#include <stdlib.h
#include <string.h>
#include <sys/types.h>
#include <sys/socket.h>
*** 264,279 ****
if (argc != 2) {
(void) printf("usage: %s IP-address\en", argv[0]);
exit (1);
}
if ((int)(addr = inet_addr(argv[1])) == -1) {
! (void) printf("IP-address must be of the form a.b.c.d\en");
exit (2);
}
hp = gethostbyaddr((char *)&addr, 4, AF_INET);
if (hp == NULL) {
! (void) printf("host information for %s not found\en", argv[1]);
exit (3);
}
for (p = hp->h_addr_list; *p != 0; p++) {
struct in_addr in;
char **q;
--- 235,250 ----
if (argc != 2) {
(void) printf("usage: %s IP-address\en", argv[0]);
exit (1);
}
if ((int)(addr = inet_addr(argv[1])) == -1) {
! (void) printf("IP-address must be of form a.b.c.d\en");
exit (2);
}
hp = gethostbyaddr((char *)&addr, 4, AF_INET);
if (hp == NULL) {
! (void) printf("host %s not found\en", argv[1]);
exit (3);
}
for (p = hp->h_addr_list; *p != 0; p++) {
struct in_addr in;
char **q;
*** 283,411 ****
(void) printf(" %s", *q);
(void) putchar('\en');
}
exit (0);
}
! .fi
! .in -2
!
! .sp
! .LP
Note that the preceding sample program is unsafe for use in multithreaded
applications.
!
! .SH FILES
! .sp
! .ne 2
! .na
! \fB\fB/etc/hosts\fR\fR
! .ad
! .RS 22n
! hosts file that associates the names of hosts with their Internet Protocol (IP)
! addresses
! .RE
!
! .sp
! .ne 2
! .na
! \fB\fB/etc/netconfig\fR\fR
! .ad
! .RS 22n
! network configuration database
! .RE
!
! .sp
! .ne 2
! .na
! \fB\fB/etc/nsswitch.conf\fR\fR
! .ad
! .RS 22n
! configuration file for the name service switch
! .RE
!
! .SH ATTRIBUTES
! .sp
! .LP
! See \fBattributes\fR(5) for descriptions of the following attributes:
! .sp
!
! .sp
! .TS
! box;
! c | c
! l | l .
! ATTRIBUTE TYPE ATTRIBUTE VALUE
! _
! MT-Level T{
! See \fBReentrant Interfaces\fR in the \fBDESCRIPTION\fR section.
! T}
! .TE
!
! .SH SEE ALSO
! .sp
! .LP
! \fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3SOCKET), \fBinet\fR(3SOCKET),
! \fBnetdb.h\fR(3HEAD), \fBnetdir\fR(3NSL), \fBhosts\fR(4), \fBnetconfig\fR(4),
! \fBnss\fR(4), \fBnsswitch.conf\fR(4), \fBattributes\fR(5)
! .SH WARNINGS
! .sp
! .LP
! The reentrant interfaces \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and
! \fBgethostent_r()\fR are included in this release on an uncommitted basis only
and are subject to change or removal in future minor releases.
! .SH NOTES
! .sp
! .LP
! To ensure that they all return consistent results, \fBgethostbyname()\fR,
! \fBgethostbyname_r()\fR, and \fBnetdir_getbyname()\fR are implemented in terms
of the same internal library function. This function obtains the system-wide
! source lookup policy based on the \fBinet\fR family entries in
! \fBnetconfig\fR(4) and the \fBhosts:\fR entry in \fBnsswitch.conf\fR(4).
! Similarly, \fBgethostbyaddr()\fR, \fBgethostbyaddr_r()\fR, and
! \fBnetdir_getbyaddr()\fR are implemented in terms of the same internal library
! function. If the \fBinet\fR family entries in \fBnetconfig\fR(4) have a ``-''
! in the last column for \fBnametoaddr\fR libraries, then the entry for
! \fBhosts\fR in \fBnsswitch.conf\fR will be used; \fBnametoaddr\fR libraries in
! that column will be used, and \fBnsswitch.conf\fR will not be consulted.
! .sp
! .LP
! There is no analogue of \fBgethostent()\fR and \fBgethostent_r()\fR in the
! netdir functions, so these enumeration functions go straight to the \fBhosts\fR
! entry in \fBnsswitch.conf\fR. Thus enumeration can return results from a
! different source than that used by \fBgethostbyname()\fR,
! \fBgethostbyname_r()\fR, \fBgethostbyaddr()\fR, and \fBgethostbyaddr_r()\fR.
! .sp
! .LP
! All the functions that return a \fBstruct hostent\fR must always return the
! \fIcanonical name\fR in the \fIh_name\fR 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
! \fBhostent\fR. Different sources might do that in different ways. If there is
! more than one alias and more than one address in \fBhostent\fR, no pairing is
implied between them.
! .sp
! .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 \fBSORT_ADDRS\fR to FALSE in the
! \fB/etc/default/nss\fR file, the system does not put the local subnet addresses
! first. See \fBnss\fR(4) for more information.
! .sp
! .LP
! When compiling multithreaded applications, see \fBIntro\fR(3), \fBMULTITHREADED
! APPLICATIONS\fR, for information about the use of the \fB_REENTRANT\fR flag.
! .sp
! .LP
! Use of the enumeration interfaces \fBgethostent()\fR and \fBgethostent_r()\fR
! is discouraged; enumeration might not be supported for all database sources.
! The semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4).
! .sp
! .LP
The current implementations of these functions only return or accept addresses
! for the Internet address family (type \fBAF_INET\fR).
! .sp
! .LP
! The form for an address of type \fBAF_INET\fR is a \fBstruct in_addr\fR defined
! in <\fBnetinet/in.h\fR>. The functions described in \fBinet\fR(3SOCKET), and
! illustrated in the \fBEXAMPLES\fR section, are helpful in constructing and
manipulating addresses in this form.
--- 254,448 ----
(void) printf(" %s", *q);
(void) putchar('\en');
}
exit (0);
}
! .Ed
! .Lp
Note that the preceding sample program is unsafe for use in multithreaded
applications.
! .Sh ERRORS
! The reentrant functions
! .Fn gethostbyname_r
! and
! .Fn gethostbyaddr_r
! 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. See
! .Xr Intro 2
! for the proper usage and interpretation of
! .Va errno
! in multithreaded applications.
! .Lp
! The reentrant functions
! .Fn gethostbyname_r
! and
! .Fn gethostbyaddr_r
! set the integer pointed to by
! .Fa h_errnop
! to one of these values in case of error.
! .Lp
! On failures, the non-reentrant functions
! .Fn gethostbyname
! and
! .Fn gethostbyaddr
! set a global integer
! .Va h_errno
! to indicate one of
! these error codes
! .Po defined in
! .In netdb.h Pc :
! .Dv HOST_NOT_FOUND ,
! .Dv TRY_AGAIN ,
! .Dv NO_RECOVERY ,
! .Dv NO_DATA ,
! and
! .Dv NO_ADDRESS .
! .Lp
! If a resolver is provided with a malformed address, or if any other error
! occurs before
! .Fn gethostbyname
! is resolved, then
! .Fn gethostbyname
! returns an internal error with a value of \(mi1.
! .Lp
! The
! .Fn gethostbyname
! function will set
! .Va h_errno
! to
! .Dv NETDB_INTERNAL
! when it returns a
! .Dv NULL
! value.
! .Sh INTERFACE STABILITY
! The
! .Fn gethostbyname
! and
! .Fn gethostbyaddr
! functions are
! .Sy Obsolete Standard .
! .Lp
! The
! .Fn gethostbyname_r
! and
! .Fn gethostbyaddr_r
! functions are
! .Sy Obsolete Uncommitted .
! .Sh MT-LEVEL
! The
! .Fn gethostbyname
! and
! .Fn gethostbyaddr
! functions are
! .Sy Unsafe .
! .Lp
! The
! .Fn gethostbyname_r
! and
! .Fn gethostbyaddr_r
! functions are
! .Sy Safe .
! .Sh SEE ALSO
! .Xr Intro 2 ,
! .Xr netdb.h 3HEAD ,
! .Xr netdir 3NSL ,
! .Xr byteorder 3SOCKET,
! .Xr getaddrinfo 3SOCKET
! .Xr getnameinfo 3SOCKET
! .Xr inet 3SOCKET ,
! .Xr hosts 4 ,
! .Xr nss 4 ,
! .Xr nsswitch.conf 4 ,
! .Xr standards 5
! .Sh NOTES
! The reentrant interfaces
! .Fn gethostbyname_r
! and
! .Fn gethostbyaddr_r
! are included in this release on an uncommitted basis only
and are subject to change or removal in future minor releases.
! .Lp
! To ensure that they all return consistent results,
! .Fn gethostbyname ,
! .Fn gethostbyname_r ,
! and
! .Xr netdir_getbyname 3NSL
! are implemented in terms
of the same internal library function. This function obtains the system-wide
! source lookup policy based on the
! .Sy hosts:
! entry in
! .Xr nsswitch.conf 4 .
! Similarly,
! .Fn gethostbyaddr ,
! .Fn gethostbyaddr_r ,
! and
! .Xr netdir_getbyaddr 3NSL
! are implemented in terms of the same internal library
! function, which also is driven by the
! .Sy hosts:
! entry in
! .Xr nsswitch.conf 4 .
! .Lp
! These 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
The current implementations of these functions only return or accept addresses
! for the Internet address family
! .Po type Dv AF_INET Pc .
! .Lp
! The form for an address of type
! .Dv AF_INET
! is a
! .Vt "struct in_addr"
! defined
! .In netinet/in.h .
! The functions described in
! .Xr inet 3SOCKET ,
! and illustrated in the
! .Sx EXAMPLES
! section, are helpful in constructing and
manipulating addresses in this form.
+ .Sh STANDARDS
+ The
+ .Fn gethostbyaddr
+ and
+ .Fn gethostbyname
+ functions were introduced in
+ .Bx 4.2 ,
+ and standardized in
+ .St -xns5.2
+ and
+ .St -p1003.1-2001 .
+ They were subsequently removed from
+ .St -p1003.1-2008 .