Sockets Library Functions getnetbyname(3SOCKET)
NAME
getnetbyname, getnetbynamer, getnetbyaddr, getnetbyaddrr,
getnetent, getnetentr, setnetent, endnetent - get network
entry
SYNOPSIS
cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]
#include
struct netent *getnetbyname(const char *name);
struct netent *getnetbynamer(const char *name, struct netent *result,
char *buffer, int buflen);
struct netent *getnetbyaddr(long net, int type);
struct netent *getnetbyaddrr(long net, int type, struct netent *result,
char *buffer, int buflen);
struct netent *getnetent(void);
struct netent *getnetentr(struct netent *result, char *buffer,
int buflen);
int setnetent(int stayopen);
int endnetent(void);
DESCRIPTION
These functions are used to obtain entries for networks. An
entry may come from any of the sources for networks speci-
fied in the /etc/nsswitch.conf file. See nsswitch.conf(4).
getnetbyname() searches for a network entry with the network
name specified by the character string parameter name.
getnetbyaddr() searches for a network entry with the network
address specified by net. The parameter type specifies the
family of the address. This should be one of the address
families defined in . See the NOTES section
below for more information.
SunOS 5.11 Last change: 4 Nov 2004 1
Sockets Library Functions getnetbyname(3SOCKET)
Network numbers and local address parts are returned as
machine format integer values, that is, in host byte order.
See also inet(3SOCKET).
The netent.nnet member in the netent structure pointed to
by the return value of the above functions is calculated by
inetnetwork(). The inetnetwork() function returns a value
in host byte order that is aligned based upon the input
string. For example:
Text Value
"10" 0x0000000a
"10.0" 0x00000a00
"10.0.1" 0a000a0001
"10.0.1.28" 0x0a000180
Commonly, the alignment of the returned value is used as a
crude approximate of pre-CIDR (Classless Inter-Domain Rout-
ing) subnet mask. For example:
inaddrt addr, mask;
addr = inetnetwork(netname);
mask= ~(inaddrt)0;
if ((addr & INCLASANET) == 0)
addr <<= 8, mask <<= 8;
if ((addr & INCLASANET) == 0)
addr <<= 8, mask <<= 8;
if ((addr & INCLASANET) == 0)
addr <<= 8, mask <<= 8;
This usage is deprecated by the CIDR requirements. See
Fuller, V., Li, T., Yu, J., and Varadhan, K. RFC 1519,
Classless Inter-Domain Routing (CIDR): an Address Assignment
and Aggregation Strategy. Network Working Group. September
1993.
The functions setnetent(), getnetent(), and endnetent() are
used to enumerate network entries from the database.
setnetent() sets (or resets) the enumeration to the begin-
ning of the set of network entries. This function should be
called before the first call to getnetent(). Calls to
SunOS 5.11 Last change: 4 Nov 2004 2
Sockets Library Functions getnetbyname(3SOCKET)
getnetbyname() and getnetbyaddr() leave the enumeration
position in an indeterminate state. If the stayopen flag is
non-zero, the system may keep allocated resources such as
open file descriptors until a subsequent call to end-
netent().
Successive calls to getnetent() return either successive
entries or NUL, indicating the end of the enumeration.
endnetent() 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
endnetent().
Reentrant Interfaces
The functions getnetbyname(), getnetbyaddr(), and get-
netent() use static storage that is reused in each call,
making these routines unsafe for use in multi-threaded
applications.
The functions getnetbynamer(), getnetbyaddrr(), and
getnetentr() provide reentrant interfaces for these opera-
tions.
Each reentrant interface performs the same operation as its
non-reentrant counterpart, named by removing the ``r'' suf-
fix. 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.
Each reentrant interface takes the same parameters as its
non-reentrant counterpart, as well as the following addi-
tional parameters. The parameter result must be a pointer to
a struct netent structure allocated by the caller. On suc-
cessful completion, the function returns the network entry
in this structure. The parameter buffer 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 struct netent result point to
data stored within this buffer. See RETURN VALUES. The
buffer must be large enough to hold all of the data associ-
ated with the network entry. The parameter buflen should
give the size in bytes of the buffer indicated by buffer.
SunOS 5.11 Last change: 4 Nov 2004 3
Sockets Library Functions getnetbyname(3SOCKET)
For enumeration in multi-threaded applications, the position
within the enumeration is a process-wide property shared by
all threads. setnetent() may be used in a multi-threaded
application but resets the enumeration position for all
threads. If multiple threads interleave calls to
getnetentr(), the threads will enumerate disjointed subsets
of the network database.
Like their non-reentrant counterparts, getnetbynamer() and
getnetbyaddrr() leave the enumeration position in an
indeterminate state.
RETURN VALUES
Network entries are represented by the struct netent struc-
ture defined in .
The functions getnetbyname(), getnetbynamer, getnetbyaddr,
and getnetbyaddrr() each return a pointer to a struct
netent if they successfully locate the requested entry; oth-
erwise they return NUL.
The functions getnetent() and getnetentr() each return a
pointer to a struct netent if they successfully enumerate an
entry; otherwise they return NUL, indicating the end of the
enumeration.
The functions getnetbyname(), getnetbyaddr(), and get-
netent() 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.
When the pointer returned by the reentrant functions
getnetbynamer(), getnetbyaddrr(), and getnetentr() is
non-NUL, it is always equal to the result pointer that was
supplied by the caller.
The functions setnetent() and endnetent() return 0 on suc-
cess.
ERORS
The reentrant functions getnetbynamer(), getnetbyaddrr and
getnetentr() will return NUL and set errno to ERANGE if
the length of the buffer supplied by caller is not large
enough to store the result. See Intro(2) for the proper
usage and interpretation of errno in multi-threaded applica-
tions.
SunOS 5.11 Last change: 4 Nov 2004 4
Sockets Library Functions getnetbyname(3SOCKET)
FILES
/etc/networks network name database
/etc/nsswitch.conf configuration file for the name ser-
vice switch
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
SEE ALSO
Intro(2), Intro(3), byteorder(3SOCKET), inet(3SOCKET),
netdb.h(3HEAD), networks(4), nsswitch.conf(4), attributes(5)
Fuller, V., Li, T., Yu, J., and Varadhan, K. RFC 1519,
Classless Inter-Domain Routing (CIDR): an Address Assignment
and Aggregation Strategy. Network Working Group. September
1993.
WARNINGS
The reentrant interfaces getnetbynamer(), getnetbyaddrr(),
and getnetentr() are included in this release on an uncom-
mitted basis only, and are subject to change or removal in
future minor releases.
NOTES
The current implementation of these functions only return or
accept network numbers for the Internet address family (type
AFINET). The functions described in inet(3SOCKET) may be
helpful in constructing and manipulating addresses and net-
work numbers in this form.
When compiling multi-threaded applications, see Intro(3),
Notes On Multithread Applications, for information about the
use of the RENTRANT flag.
Use of the enumeration interfaces getnetent() and
getnetentr() is discouraged; enumeration may not be
SunOS 5.11 Last change: 4 Nov 2004 5
Sockets Library Functions getnetbyname(3SOCKET)
supported for all database sources. The semantics of
enumeration are discussed further in nsswitch.conf(4).
SunOS 5.11 Last change: 4 Nov 2004 6
|
