Networking Services Library Functions            getnetpath(3NSL)

NAME
     getnetpath,  setnetpath,  endnetpath  -  get  /etc/netconfig
     entry corresponding to NETPATH component

SYNOPSIS
     #include <netconfig.h>

     struct netconfig *getnetpath(void *handlep);

     void *setnetpath(void);

     int endnetpath(void *handlep);

DESCRIPTION
     The routines described on this page are part of the  Network
     Selection  component. They provide the application access to
     the system network configuration  database,  /etc/netconfig,
     as it is "filtered" by the NETPATH environment variable. See
     environ(5). See getnetconfig(3NSL) for other  routines  that
     also access the network configuration database directly. The
     NETPATH variable is a list of colon-separated network  iden-
     tifiers.

     getnetpath() returns a pointer to  the   netconfig  database
     entry  corresponding  to the first  valid NETPATH component.
     The netconfig entry is formatted as a struct  netconfig.  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.

     A call to setnetpath() "binds" to or "rewinds" NETPATH. set-
     netpath()  must  be  called before the first call to getnet-
     path() and may be called at any other  time.  It  returns  a
     handle that is used by getnetpath().

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

     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"  from  NETPATH  when
     processing  is complete, releasing resources for reuse. Pro-
     grammers should be aware, however, that  endnetpath()  frees
     all  memory allocated by getnetpath() for the struct netcon-
     fig data structure. endnetpath() returns 0 on success and -1

SunOS 5.8           Last change: 30 Dec 1996                    1

Networking Services Library Functions            getnetpath(3NSL)

     on failure (for example, if setnetpath() was not called pre-
     viously).

RETURN VALUES
     setnetpath() returns a handle that is used by  getnetpath().
     In  case of an error, setnetpath() returns NULL. nc_perror()
     or nc_sperror() can be used to  print  out  the  reason  for
     failure. See getnetconfig(3NSL).

     When first called, getnetpath() returns  a  pointer  to  the
     netconfig  database  entry  corresponding to the first valid
     NETPATH component. When NETPATH has been exhausted,  getnet-
     path() returns NULL.

     endnetpath() returns 0 on success and  -1  on  failure  (for
     example, if setnetpath() was not called previously).

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|

SEE ALSO
     getnetconfig(3NSL), netconfig(4), attributes(5), environ(5)

     ONC+  Developer's  Guide  Transport  Interfaces  Programming
     Guide

SunOS 5.8           Last change: 30 Dec 1996                    2