NETPATH Access to netconfig(4) Data

Three routines access the network configuration database indirectly through the NETPATH environment variable. The variable specifies the transport or transports an application is to use and the order to try them. NETPATH components are read from left to right. The functions have the following interfaces:

#include <netconfig.h>

void *setnetpath(void);
struct netconfig *getnetpath(void *);
int endnetpath(void *);

A call to setnetpath(3NSL) initializes the search of NETPATH. It returns a pointer to a database that contains the entries specified in a NETPATH variable. The pointer, called a handle, is used to traverse this database with getnetpath(3NSL). The setnetpath(3NSL) function must be called before the first call to getnetpath(3NSL).

When first called, getnetpath(3NSL) returns a pointer to the netconfig(4) file entry that corresponds to the first component of the NETPATH variable. On each subsequent call, getnetpath(3NSL) returns a pointer to the netconfig(4) entry that corresponds to the next component of the NETPATH variable; getnetpath(3NSL) returns NULL if there are no more components in NETPATH. A call to getnetpath(3NSL) without an initial call to setnetpath(3NSL) causes an error; getnetpath(3NSL) requires the pointer returned by setnetpath(3NSL) as an argument.

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

If the NETPATH variable is unset, getnetpath(3NSL) behaves as if NETPATH were set to the sequence of default or visible transports in the netconfig(4) database, in the order in which they are listed.

endnetpath(3NSL) is called to release the database pointer to elements in the NETPATH variable when processing is complete. endnetpath(3NSL) fails if setnetpath(3NSL) was not called previously. Example 4-3 shows the setnetpath(3NSL), getnetpath(3NSL), and endnetpath(3NSL) routines.

Example 4-3 setnetpath(3NSL), getnetpath(3NSL), and endnetpath(3NSL) Functions

#include <netconfig.h>

void *handlep;
struct netconfig *nconf;

if ((handlep = setnetpath()) == (void *)NULL) {
   nc_perror(argv[0]);
   exit(1);
}

while ((nconf = getnetpath(handlep)) != (struct netconfig *)NULL)
{
   /*
    * nconf now describes a transport provider.
    */
}
endnetpath(handlep);

The netconfig(4) structures obtained through getnetpath(3NSL) become invalid after the execution of endnetpath(3NSL). To preserve the data in the structure, use getnetconfigent(nconf->nc_netid) to copy them into a new data structure.