getprotobyname(3SOCKET) 				     Sockets Library Functions					   getprotobyname(3SOCKET)

NAME

       getprotobyname, getprotobyname_r, getprotobynumber, getprotobynumber_r, getprotoent, getprotoent_r, setprotoent, endprotoent - get protocol
       entry

SYNOPSIS

       cc [ flag ... ] file ... -lsocket  -lnsl  [ library ... ]
       #include <netdb.h>

       struct protoent *getprotobyname(const char *name);

       struct protoent *getprotobyname_r(const char *name,
	    struct protoent *result, char *buffer,
	    int buflen);

       struct protoent *getprotobynumber(int proto);

       struct protoent *getprotobynumber_r(int proto, struct protoent *result,
	    char *buffer, int buflen);

       struct protoent *getprotoent(void);

       struct protoent *getprotoent_r(struct protoent *result, char *buffer,
	    int buflen);

       int setprotoent(int stayopen);

       int endprotoent(void);

DESCRIPTION

       These functions return a protocol entry. Two types of interfaces are supported: reentrant  (getprotobyname_r(),	getprotobynumber_r(),  and
       getprotoent_r())  and  non-reentrant (getprotobyname(), getprotobynumber(), and getprotoent()). The reentrant functions can be used in sin-
       gle-threaded applications and are safe for multithreaded applications, making them the preferred interfaces.

       The reentrant routines require additional parameters which are used to return results data. result is a pointer to a struct protoent struc-
       ture and will be where the returned results will be stored. buffer is used as storage space for elements of the returned results. buflen is
       the size of buffer and should be large enough to contain all returned data. buflen must be at least 1024 bytes.

       getprotobyname_r(), getprotobynumber_r(), and getprotoent_r() each return a protocol entry.

       The entry may come from one of the following sources: the protocols file (see protocols(4)), the NIS maps ``protocols.byname'' and ``proto-
       cols.bynumber'',  and  the  NIS+  table ``protocols''. The sources and their lookup order are specified in the /etc/nsswitch.conf file (see
       nsswitch.conf(4) for details). Some name services such as NIS will return only one name for a host, whereas others such as NIS+ or DNS will
       return all aliases.

       The getprotobyname_r() and getprotobynumber_r() functions sequentially search from the beginning of the file until a matching protocol name
       or protocol number is found, or until an EOF is encountered.

       getprotobyname() and getprotobynumber() have the same functionality as getprotobyname_r() and getprotobynumber_r()  except  that  a  static
       buffer is used to store returned results.  These functions are Unsafe in a multithreaded application.

       getprotoent_r()	enumerates  protocol  entries: successive calls to getprotoent_r() will return either successive protocol entries or NULL.
       Enumeration might not be supported by some sources. If multiple threads call getprotoent_r(), each will retrieve a subset of  the  protocol
       database.

       getprotent()  has  the same functionality as getprotent_r() except that a static buffer is used to store returned results.  This routine is
       unsafe in a multithreaded application.

       setprotoent() "rewinds" to the beginning of the enumeration of protocol entries. If the stayopen flag is non-zero, resources such  as  open
       file descriptors are not deallocated after each call to getprotobynumber_r() and getprotobyname_r(). Calls to getprotobyname_r() , The get-
       protobyname(), getprotobynumber_r(), and getprotobynumber() functions might leave the enumeration in an	indeterminate  state,  so  setpro-
       toent()	should be called before the first call to getprotoent_r() or getprotoent(). The setprotoent() function has process-wide scope, and
       ``rewinds'' the protocol entries for all threads calling getprotoent_r() as well as main-thread calls to getprotoent().

       The endprotoent() function can be called to indicate that protocol processing is complete; the system may then  close  any  open  protocols
       file,  deallocate  storage,  and  so  forth.   It is legitimate, but possibly less efficient, to call more protocol functions after endpro-
       toent().

       The internal representation of a protocol entry is a protoent structure defined in <netdb.h> with the following members:

	 char  *p_name;
	 char  **p_aliases;
	 int   p_proto;

RETURN VALUES

       The getprotobyname_r(), getprotobyname(), getprotobynumber_r(), and getprotobynumber() functions return a pointer to a struct  protoent	if
       they successfully locate the requested entry; otherwise they return NULL.

       The  getprotoent_r()  and  getprotoent() functions return a pointer to a struct protoent if they successfully enumerate an entry; otherwise
       they return NULL, indicating the end of the enumeration.

ERRORS

       The getprotobyname_r(), getprotobynumber_r(), and getprotoent_r() functions will fail if:

       ERANGE	 The length of the buffer supplied by the caller is not large enough to store the result.

FILES

       /etc/protocols

       /etc/nsswitch.conf

ATTRIBUTES

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |See NOTES below.		   |
       +-----------------------------+-----------------------------+

SEE ALSO

       Intro(3), nsswitch.conf(4), protocols(4), attributes(5), netdb.h(3HEAD)

NOTES

       Although getprotobyname_r(), getprotobynumber_r(), and getprotoent_r() are not mentioned by POSIX 1003.1:2001, they were added to  complete
       the functionality provided by similar thread-safe functions.

       When  compiling	multithreaded  applications, see  Intro(3), Notes On Multithread Applications, for information about the use of the _REEN-
       TRANT flag.

       The getprotobyname_r(), getprotobynumber_r(), and getprotoent_r() functions are reentrant and multithread safe.	The  reentrant	interfaces
       can be used in single-threaded as well as multithreaded applications and are therefore the preferred interfaces.

       The  getprotobyname(),  getprotobyaddr(),  and  getprotoent()  functions use static storage, so returned data must be copied if it is to be
       saved. Because of their use of static storage for returned data, these functions are not safe for multithreaded applications.

       The setprotoent() and endprotoent() functions have process-wide scope, and are therefore not safe in multi-threaded applications.

       Use of getprotoent_r() and getprotoent() is discouraged; enumeration is well-defined for the protocols file and is supported (albeit  inef-
       ficiently) for NIS and NIS+, but in general may not be well-defined.  The semantics of enumeration are discussed in nsswitch.conf(4).

BUGS

       Only the Internet protocols are currently understood.

SunOS 5.11							    5 Apr 2004						   getprotobyname(3SOCKET)