Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
getnetbyname(3SOCKET)	   Sockets Library Functions	 getnetbyname(3SOCKET)

NAME
       getnetbyname,  getnetbyname_r, getnetbyaddr, getnetbyaddr_r, getnetent,
       getnetent_r, setnetent, endnetent - get network entry

SYNOPSIS
       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 bu-
       flen);

       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 specified  in	the  /etc/nss-
       witch.conf file.	See nsswitch.conf(4).

       getnetbyname() searches for a network entry with	the network name spec-
       ified 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 ad-
       dress.	This  should  be  one  of  the	address	 families  defined  in
       <sys/socket.h>. See the NOTES section below for more information.

       Network	numbers	and local address parts	are returned as	machine	format
       integer values, that  is,  in  host  byte  order.  See  also  inet_net-
       work(3SOCKET).

       The  netent.n_net  member in the	netent structure pointed to by the re-
       turn value of the above functions is calculated by inet_network().  The
       inet_network()  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  ap-
       proximate of pre-CIDR (Classless	Inter-Domain Routing) subnet mask. For
       example:

       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;

       This usage is deprecated	by the CIDR requirements. See Fuller, V.,  Li,
       T.,  Yu,	 J., and Varadhan, K. RFC 1591,	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  beginning  of  the
       set  of	network	 entries.   This  function should be called before the
       first call to getnetent(). Calls	to 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 endnetent().

       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  de-
       allocate	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  getnetent()  use
       static  storage	that is	reused in each call, making these routines un-
       safe for	use in multi-threaded applications.

       The functions  getnetbyname_r(),	 getnetbyaddr_r(),  and	 getnetent_r()
       provide reentrant interfaces for	these operations.

       Each  reentrant	interface performs the same operation as its non-reen-
       trant counterpart, named	by removing the	 ``_r''	suffix.	 The reentrant
       interfaces,  however,  use  buffers supplied by the caller to store re-
       turned 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 additional	parameters.   The  pa-
       rameter result must be a	pointer	to a struct netent structure allocated
       by the caller.  On successful completion, the function returns the net-
       work 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  RE-
       TURN  VALUES.  The  buffer must be large	enough to hold all of the data
       associated 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.	setne-
       tent()  may be used in a	multi-threaded application but resets the enu-
       meration	position for all  threads.   If	 multiple  threads  interleave
       calls  to  getnetent_r(), the threads will enumerate disjointed subsets
       of the network database.

       Like their non-reentrant	 counterparts,	getnetbyname_r()  and  getnet-
       byaddr_r() leave	the enumeration	position in an indeterminate state.

RETURN VALUES
       Network	entries	are represented	by the struct netent structure defined
       in  <netdb.h>.

       The functions  getnetbyname(),  getnetbyname_r(),  getnetbyaddr(),  and
       getnetbyaddr_r()	 each return a pointer to a struct netent if they suc-
       cessfully 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  getnetent()  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 success.

ERRORS
       The reentrant functions	getnetbyname_r(), getnetbyaddr_r() and	getne-
       tent_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	applications.

FILES
       /etc/networks

       /etc/nsswitch.conf

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       Intro(2), Intro(3),  byteorder(3SOCKET),	 inet(3SOCKET),	 netdb(3HEAD),
       networks(4), nsswitch.conf (4), attributes(5)

       Fuller, V., Li, T., Yu, J., and Varadhan, K. RFC	1591, Classless	Inter-
       Domain Routing (CIDR): an Address Assignment and	Aggregation  Strategy.
       Network Working Group. September	1993.

WARNINGS
       The reentrant interfaces	getnetbyname_r(), getnetbyaddr_r(), and	getne-
       tent_r()	are included in	this release on	an uncommitted 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 network numbers in this form.

       Programs	that use the interfaces	described in this manual  page	cannot
       be  linked  statically since the	implementations	of these functions em-
       ploy 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	_REEN-
       TRANT flag.

       Use of the enumeration interfaces getnetent() and getnetent_r() is dis-
       couraged;  enumeration  may  not	be supported for all database sources.
       The semantics of	enumeration are	discussed further in nsswitch.conf(4).

SunOS 5.9			  15 Jan 2002		 getnetbyname(3SOCKET)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | FILES | ATTRIBUTES | SEE ALSO | WARNINGS | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=endnetent&sektion=3socket&manpath=SunOS+5.9>

home | help