getnetbyname
Sockets Library Functions getnetbyname(3SOCKET)NAME
getnetbyname, getnetbyname_r, getnetbyaddr, getnetbyaddr_r, getnetent, getnetent_r, setnetent, endnetent - get network entrySYNOPSIS
cc [ flag ... ] file ... -lsocket -lnsl [ library ... ] #include <netdb.h> struct netent *getnetbyname(const char *name); struct netent *getnetbyname_r(const char *name, struct netent *result, char *buffer, int buflen); struct netent *getnetbyaddr(long net, inttype); struct netent *getnetbyaddr_r(long net, inttype, struct netent *result, char *buffer, int buflen); struct netent *getnetent(void); struct netent *getnetent_r(struct netent *result, char *buffer, int buflen); int setnetent(int stayopen); int endnetent(void);DESCRIPTION
These functions are used to obtain entries for network. An entry may come from any of the sources for network 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 <sys/socket.h>. See the NOTES section below for more information. All addresses are returned in network order. In order to interpret the addresses, byteorder(3SOCKET) must be used for byte order conversion. 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.8 Last change: 23 May 1998 1 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 NULL, 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 pro- cess 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 getnetbyname_r(), getnetbyaddr_r(), and getnetent_r() provide reentrant interfaces for these opera- tions. Each reentrant interface performs the same operation as its non-reentrant counterpart, named by removing the ``_r'' suffix. The reentrant interfaces, however, use buffers sup- plied by the caller to store returned results, and are safe for use in both single-threaded and multi-threaded applica- tions. 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 successful 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. 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 SunOS 5.8 Last change: 23 May 1998 2 Sockets Library Functions getnetbyname(3SOCKET) getnetent_r(), the threads will enumerate disjointed subsets of the network database. Like their non-reentrant counterparts, getnetbyname_r() and getnetbyaddr_r() leave the enumeration position in an indeterminate state. RETURN VALUES Network entries are represented by the struct netent struc- ture defined in <netdb.h>. The functions getnetbyname(), getnetbyname_r(), getnet- byaddr(), and getnetbyaddr_r() each return a pointer to a struct netent if they successfully locate the requested entry; otherwise they return NULL. The functions getnetent() and getnetent_r() each return a pointer to a struct netent if they successfully enumerate an entry; otherwise they return NULL, 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 getnetbyname_r(), getnetbyaddr_r(), and getnetent_r() is non-NULL, it is always equal to the result pointer that was supplied by the caller. The functions setnetent() and endnetent() return 0 on suc- cess. ERRORS The reentrant functions getnetbyname_r(), getnetbyaddr_r() and getnetent_r() will return NULL 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.FILES
/etc/networks" /etc/nsswitch.conf"ATTRIBUTES
See attributes(5) for descriptions of the following attri- butes: SunOS 5.8 Last change: 23 May 1998 3 Sockets Library Functions getnetbyname(3SOCKET) ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | MT-Level | MT-Safe | |_____________________________|_____________________________|SEE ALSO
Intro(2), Intro(3), byteorder(3SOCKET), inet(3SOCKET), net- works(4), nsswitch.conf (4), attributes(5), netdb(3HEAD) WARNINGS The reentrant interfaces getnetbyname_r(), getnetbyaddr_r(), and getnetent_r() 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 AF_INET). The functions described in inet(3SOCKET) may be helpful in constructing and manipulating addresses and net- work numbers in this form. Programs that use the interfaces described in this manual page cannot be linked statically since the implementations of these functions employ dynamic loading and linking of shared objects at run time. When compiling multi-threaded applications, see Intro(3), Notes On Multithread Applications, for information about the use of the _REENTRANT flag. Use of the enumeration interfaces getnetent() and getnetent_r() is discouraged; enumeration may not be sup- ported for all database sources. The semantics of enumera- tion are discussed further in nsswitch.conf(4). SunOS 5.8 Last change: 23 May 1998 4