getnetpath(3N)                                        getnetpath(3N)


       NAME
             getnetpath - get netconfig entry corresponding to NETPATH
             component

       SYNOPSIS
             cc [options] file -lnsl
             #include <netconfig.h>
             void *setnetpath(void);
             struct netconfig *getnetpath(void *handlep);
             int endnetpath(void *handlep);
             void nc_perror (char *msg);
             char *nc_sperror (void);

       DESCRIPTION
             The five routines described on this page are part of the UNIX
             System V Network Selection component.  They provide
             application access to the system network configuration
             database, /etc/netconfig, as it is ``filtered'' by the NETPATH
             environment variable [see environ(5)].  Network Selection also
             includes routines that access the network configuration
             database directly [see getnetconfig(3N)].

             A call to setnetpath ``binds'' or ``rewinds'' NETPATH.
             setnetpath must be called before the first call to getnetpath
             and may be called at any other time.  It returns a handle that
             is used by getnetpath.  setnetpath will fail if the netconfig
             database is not present.  If NETPATH is unset, or if NETPATH
             is set but null, the set of visible networks constitutes a
             default NETPATH for use by setnetpath.

             When first called, getnetpath returns a pointer to the
             netconfig database entry corresponding to the first valid
             NETPATH component.  The netconfig entry is formatted as a
             netconfig structure.  On each subsequent call, getnetpath
             returns a pointer to the netconfig entry that corresponds to
             the next valid NETPATH component.  getnetpath can thus be used
             to search the netconfig database for all networks included in
             the NETPATH variable.  When NETPATH has been exhausted,
             getnetpath returns NULL.

             getnetpath silently ignores invalid NETPATH components.  A
             NETPATH component is invalid if there is no corresponding
             entry in the netconfig database.





                           Copyright 1994 Novell, Inc.               Page 1

      getnetpath(3N)                                        getnetpath(3N)


            If the NETPATH variable is unset, getnetpath behaves as if
            NETPATH were set to the sequence of ``default'' or ``visible''
            networks in the netconfig database, in the order in which they
            are listed.

            endnetpath may be called to ``unbind'' NETPATH when processing
            is complete, releasing resources for reuse.  Programmers
            should be aware, however, that endnetpath frees all memory
            allocated by setnetpath.  endnetpath returns 0 on success and
            -1 on failure (for example, if setnetpath was not called
            previously).

            nc_perror prints a message to the standard error indicating
            why any of the above routines failed.  The message is
            prepended with string msg and a colon.  A NEWLINE is appended
            at the end of the message.

            nc_sperror is similar to nc_perror but instead of sending the
            message to the standard error indicating why the network
            selection routines failed, it returns a pointer to the
            message.

         Files
            /usr/lib/locale/<locale>/LC_MESSAGES/uxnsl

      REFERENCES
            environ(5), getnetconfig(3N), netconfig(4)

      NOTICES
            nc_sperror returns a pointer to static data that is
            overwritten on each call.  For multi-threaded applications,
            each thread is allocated a separate message storage area.

            Functions that provide successive entries in files on
            successive calls must be called from a single thread.













                          Copyright 1994 Novell, Inc.               Page 2