getprotoent(3N)                                             getprotoent(3N)




 NAME
      getprotoent(), getprotoent_r(), getprotobynumber(),
      getprotobynumber_r(), getprotobyname(), getprotobyname_r(),
      setprotoent(), setprotoent_r(), endprotoent(), endprotoent_r() - get
      protocol entry


 SYNOPSIS
      #include <netdb.h>

      struct protoent *getprotoent(void);

      int getprotoent_r(struct protoent *result,
                        struct protoent_data *buffer);

      struct protoent *getprotobyname(const char *name);

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

      struct protoent *getprotobynumber(int proto);

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

      int setprotoent(int stayopen);

      int setprotoent_r(int stayopen, struct protoent_data *buffer);

      int endprotoent(void);

      int endprotoent_r(struct protoent_data *buffer);

      _XOPEN_SOURCE_EXTENDED only
      void setprotoent(int stayopen);
      void endprotoent(void);

 DESCRIPTION
      The getprotoent(), getprotobyname(), and getprotobynumber() functions
      each return a pointer to a structure of type protoent containing the
      broken-out fields of a line in the network protocol data base,
      /etc/protocols.

      The members of this structure are:

           p_name         The official name of the protocol.

           p_aliases      A null-terminated list of alternate names for the
                          protocol.

           p_proto        The protocol number.

      Functions behave as follows:

           getprotoent()             Reads the next line of the file,
                                     opening the file if necessary.

           setprotoent()             Opens and rewinds the file.  If the
                                     stayopen flag is non-zero, the protocol
                                     data base is not closed after each call
                                     to getprotoent() (either directly or
                                     indirectly through one of the other
                                     getproto* calls).

           endprotoent()             Closes the file.

           getprotobyname()
           getprotobynumber()        Each sequentially searches from the
                                     beginning of the file until a matching
                                     protocol name (among either the
                                     official names or the aliases) or
                                     protocol number is found, or until EOF
                                     is encountered.

           If the system is running the Network Information Service (NIS)
           services, getprotobyname() and getprotobynumber() get the
           protocol information from the NIS server (see ypserv(1M) and
           ypfiles(4)).

    Reentrant Interfaces
      getprotoent_r(), getprotobyname_r(), and getprotobynumber_r() expect
      to be passed the address of a struct protoent and will store the
      result at the supplied location.  An additional parameter, a pointer
      to a struct protoent_data, must also be supplied.  This structure is
      used to store data, to which fields in the struct protoent will point,
      as well as state information such as open file descriptors.  The
      struct protoent_data is defined in the file <netdb.h>.

      setprotoent_r() and endprotoent_r() are to be used only in conjunction
      with getprotoent_r() and take the same pointer to a struct
      protoent_data as a parameter.  If the Network Information Service is
      being used, setprotoent_r() initializes an internal database key.  If
      the /etc/protocols file is being used, setprotoent_r() opens or
      rewinds the file.  endprotoent_r() should always be called to ensure
      that files are closed and internally allocated data structures are
      released.

      The stayopen parameter to setprotoent_r() currently has no effect.
      However, setprotoent() can still be used to keep the /etc/protocols
      file open when making calls to getprotobyname_r() and
      getprotobynumber_r().

      The proto_fp field in the struct protoent_data must be initialized to
      NULL before it is passed to either getprotoent_r() or setprotoent_r()
      for the first time.  Thereafter it should not be modified in any way.
      This is the only protoent_data field that should ever be explicitly
      accessed.

    Name Service Switch-Based Operation
      The library routines, getprotobyname(), getprotobynumber(),
      getprotoent(), and their reentrant counterparts, internally call the
      name service switch to access the "protocols" database lookup policy
      configured in the /etc/nsswitch.conf file (see switch(4)).  The lookup
      policy defines the order and the criteria of the supported name
      services used to resolve protocol names and numbers.

 RETURN VALUE
      getprotoent(), getprotobyname(), and getprotobynumber() return a null
      pointer (0) on EOF or when they are unable to open /etc/protocols.

      For the reentrant (_r) versions of these routines, -1 will be returned
      if the operation is unsuccessful or, in the case of getprotoent_r(),
      if the end of the protocols list has been reached.  0 is returned
      otherwise.

 EXAMPLES
      The following code excerpt counts the number of protocols entries:

           int count = 0;
           struct protoent protobuf;
           struct protoent_data pdbuf;

           pdbuf.proto_fp = NULL;
           (void) setprotoent_r(0, &pdbuf);
           while (getprotoent_r(&protobuf, &pdbuf) != -1)
                count++;
           (void) endprotoent_r(&pdbuf);

 WARNINGS
      In the non-reentrant versions of these routines, all information is
      contained in a static area so it must be copied if it is to be saved.

      getprotoent(), getprotobynumber(), getprotobyname(), setprotoent(),
      and endprotoent() are unsafe in multi-thread applications.
      getprotoent_r(), getprotobynumber_r(), getprotobyname_r(),
      setprotoent_r(), and endprotoent_r() are MT-Safe and should be used
      instead.

 AUTHOR
      getprotoent() was developed by the University of California, Berkeley.

 FILES
      /etc/protocols

 SEE ALSO
      ypserv(1M), protocols(4), ypfiles(4).

 STANDARDS CONFORMANCE
      getprotoent(): XPG4

 Hewlett-Packard Company            - 4 -    HP-UX Release 10.20:  July 1996