Manual Pages for UNIX Operating System command usage for man getprotobynumber

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 

     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 inter-
     faces    are   supported:   reentrant   (getprotobyname_r(),
     getprotobynumber_r(), and getprotoent_r()) and non-reentrant
     (getprotobyname(),  getprotobynumber(),  and getprotoent()).
     The reentrant  functions  can  be  used  in  single-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 structure 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



SunOS 5.11          Last change: 10 Dec 2009                    1






Sockets Library Functions                 getprotobyname(3SOCKET)



     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)),  and  the  NIS  maps
     ``protocols.byname'' and ``protocols.bynumber''. 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 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  func-
     tionality  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 pro-
     tocol 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 applica-
     tion.


     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  setprotoent()  should be called before the first
     call to getprotoent_r() or getprotoent(). The  setprotoent()



SunOS 5.11          Last change: 10 Dec 2009                    2






Sockets Library Functions                 getprotobyname(3SOCKET)



     function  has process-wide scope, and ``rewinds'' the proto-
     col 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 endprotoent().


     The internal representation of a protocol entry  is  a  pro-
     toent  structure  defined  in    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  attri-
     butes:





SunOS 5.11          Last change: 10 Dec 2009                    3






Sockets Library Functions                 getprotobyname(3SOCKET)



     ____________________________________________________________
    |       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 _REENTRANT 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 inefficiently) for NIS, but in general may
     not  be well-defined.  The semantics of enumeration are dis-
     cussed in nsswitch.conf(4).

BUGS
     Only the Internet protocols are currently understood.





SunOS 5.11          Last change: 10 Dec 2009                    4