'\" te
.\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" Copyright (c) 1983 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.
.TH GETNETBYNAME 3SOCKET "Nov 4, 2004"
.SH NAME
getnetbyname, getnetbyname_r, getnetbyaddr, getnetbyaddr_r, getnetent,
getnetent_r, setnetent, endnetent \- get network entry
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
#include <netdb.h>

\fBstruct netent *\fR\fBgetnetbyname\fR(\fBconst char *\fR\fIname\fR);
.fi

.LP
.nf
\fBstruct netent *\fR\fBgetnetbyname_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct netent *\fR\fIresult\fR,
     \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
.fi

.LP
.nf
\fBstruct netent *\fR\fBgetnetbyaddr\fR(\fBlong\fR \fInet\fR, \fBint\fR \fItype\fR);
.fi

.LP
.nf
\fBstruct netent *\fR\fBgetnetbyaddr_r\fR(\fBlong\fR \fInet\fR, \fBint\fR \fItype\fR, \fBstruct netent *\fR\fIresult\fR,
     \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR);
.fi

.LP
.nf
\fBstruct netent *\fR\fBgetnetent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBstruct netent *\fR\fBgetnetent_r\fR(\fBstruct netent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR,
     \fBint\fR \fIbuflen\fR);
.fi

.LP
.nf
\fBint\fR \fBsetnetent\fR(\fBint\fR \fIstayopen\fR);
.fi

.LP
.nf
\fBint\fR \fBendnetent\fR(\fBvoid\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions are used to obtain entries for networks. An entry may come from
any of the sources for \fBnetworks\fR specified in the \fB/etc/nsswitch.conf\fR
file. See \fBnsswitch.conf\fR(4).
.sp
.LP
\fBgetnetbyname()\fR searches for a network entry with the network name
specified by the character string parameter \fIname\fR.
.sp
.LP
\fBgetnetbyaddr()\fR searches for a network entry with the network address
specified by \fInet\fR. The parameter \fBtype\fR specifies the family of the
address. This should be one of the address families defined in
<\fBsys/socket.h\fR>. See the \fBNOTES\fR section below for more information.
.sp
.LP
Network numbers and local address parts are returned as machine format integer
values, that is, in host byte order. See also \fBinet\fR(3SOCKET).
.sp
.LP
The \fBnetent.n_net\fR member in the \fBnetent\fR structure pointed to by the
return value of the above functions is calculated by \fBinet_network()\fR. The
\fBinet_network()\fR function returns a value in host byte order that is
aligned based upon the input string. For example:
.sp

.sp
.TS
c c
l l .
Text	Value
\fB"10"\fR	\fB0x0000000a\fR
\fB"10.0"\fR	\fB0x00000a00\fR
\fB"10.0.1"\fR	\fB0a000a0001\fR
\fB"10.0.1.28\fR"	\fB0x0a000180\fR
.TE

.sp
.LP
Commonly, the alignment of the returned value is used as a crude approximate of
pre-CIDR (Classless Inter-Domain Routing) subnet mask. For example:
.sp
.in +2
.nf
in_addr_t addr, mask;

addr = inet_network(net_name);
mask= ~(in_addr_t)0;
if ((addr & IN_CLASSA_NET) == 0)
       addr <<= 8, mask <<= 8;
if ((addr & IN_CLASSA_NET) == 0)
       addr <<= 8, mask <<= 8;
if ((addr & IN_CLASSA_NET) == 0)
       addr <<= 8, mask <<= 8;
.fi
.in -2

.sp
.LP
This usage is deprecated by the CIDR requirements. See Fuller, V., Li, T., Yu,
J., and Varadhan, K. \fIRFC 1519, Classless Inter-Domain Routing (CIDR): an
Address Assignment and Aggregation Strategy\fR. Network Working Group.
September 1993.
.sp
.LP
The functions \fBsetnetent()\fR, \fBgetnetent()\fR, and \fBendnetent()\fR are
used to enumerate network entries from the database.
.sp
.LP
\fBsetnetent()\fR sets (or resets) the enumeration to the beginning of the set
of network entries. This function should be called before the first call to
\fBgetnetent()\fR. Calls to \fBgetnetbyname()\fR and \fBgetnetbyaddr()\fR leave
the enumeration position in an indeterminate state. If the \fIstayopen\fR flag
is non-zero, the system may keep allocated resources such as open file
descriptors until a subsequent call to \fBendnetent()\fR.
.sp
.LP
Successive calls to \fBgetnetent()\fR return either successive entries or
\fBNULL\fR, indicating the end of the enumeration.
.sp
.LP
\fBendnetent()\fR may be called to indicate that the caller expects to do no
further network entry retrieval operations; the system may then deallocate
resources it was using. It is still allowed, but possibly less efficient, for
the process to call more network entry retrieval functions after calling
\fBendnetent()\fR.
.SS "Reentrant Interfaces"
.sp
.LP
The functions \fBgetnetbyname()\fR, \fBgetnetbyaddr()\fR, and \fBgetnetent()\fR
use static storage that is reused in each call, making these routines unsafe
for use in multi-threaded applications.
.sp
.LP
The functions \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r()\fR, and
\fBgetnetent_r()\fR 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 are safe for use in both single-threaded and multi-threaded
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 netent\fR structure allocated by
the caller. On successful completion, the function returns the network 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 network
entry data. All of the pointers within the returned \fBstruct netent\fR
\fIresult\fR point to data stored within this buffer. See \fBRETURN VALUES\fR.
The buffer must be large enough to hold all of the data associated with the
network entry. The parameter \fIbuflen\fR should give the size in bytes of the
buffer indicated by \fIbuffer\fR.
.sp
.LP
For enumeration in multi-threaded applications, the position within the
enumeration is a process-wide property shared by all threads. \fBsetnetent()\fR
may be used in a multi-threaded application but resets the enumeration position
for all threads. If multiple threads interleave calls to \fBgetnetent_r()\fR,
the threads will enumerate disjointed subsets of the network database.
.sp
.LP
Like their non-reentrant counterparts, \fBgetnetbyname_r()\fR and
\fBgetnetbyaddr_r()\fR leave the enumeration position in an indeterminate
state.
.SH RETURN VALUES
.sp
.LP
Network entries are represented by the \fBstruct netent\fR structure defined in
\fB<netdb.h>\fR\&.
.sp
.LP
The functions \fBgetnetbyname()\fR, \fBgetnetbyname_r\fR, \fBgetnetbyaddr\fR,
and \fBgetnetbyaddr_r()\fR each return a pointer to a \fBstruct netent\fR if
they successfully locate the requested entry; otherwise they return \fBNULL\fR.
.sp
.LP
The functions \fBgetnetent()\fR and \fBgetnetent_r()\fR each return a pointer
to a \fBstruct netent\fR if they successfully enumerate an entry; otherwise
they return \fBNULL\fR, indicating the end of the enumeration.
.sp
.LP
The functions \fBgetnetbyname()\fR, \fBgetnetbyaddr()\fR, and \fBgetnetent()\fR
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 \fBgetnetbyname_r()\fR,
\fBgetnetbyaddr_r()\fR, and \fBgetnetent_r()\fR is non-\fBNULL\fR, it is always
equal to the \fIresult\fR pointer that was supplied by the caller.
.sp
.LP
The functions \fBsetnetent()\fR and \fBendnetent()\fR return \fB0\fR on
success.
.SH ERRORS
.sp
.LP
The reentrant functions \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r\fR and
\fBgetnetent_r()\fR will return \fBNULL\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
\fIerrno\fR in multi-threaded applications.
.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/networks\fR\fR
.ad
.RS 22n
network name 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	MT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3SOCKET), \fBinet\fR(3SOCKET),
\fBnetdb.h\fR(3HEAD), \fBnetworks\fR(4), \fBnsswitch.conf\fR(4),
\fBattributes\fR(5)
.sp
.LP
Fuller, V., Li, T., Yu, J., and Varadhan, K. \fIRFC 1519, Classless
Inter-Domain Routing (CIDR): an Address Assignment and Aggregation Strategy\fR.
Network Working Group. September 1993.
.SH WARNINGS
.sp
.LP
The reentrant interfaces \fBgetnetbyname_r()\fR, \fBgetnetbyaddr_r()\fR, and
\fBgetnetent_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
The current implementation of these functions only return or accept network
numbers for the Internet address family (type \fBAF_INET\fR). The functions
described in \fBinet\fR(3SOCKET) may be helpful in constructing and
manipulating addresses and network numbers in this form.
.sp
.LP
When compiling multi-threaded applications, see \fBIntro\fR(3), \fINotes On
Multithread Applications\fR, for information about the use of the
\fB_REENTRANT\fR flag.
.sp
.LP
Use of the enumeration interfaces \fBgetnetent()\fR and \fBgetnetent_r()\fR is
discouraged; enumeration may not be supported for all database sources. The
semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4).