Network services

Routines that access netconfig via NETPATH

The three routines described here access the network configuration database indirectly through the NETPATH environment variable. The user is thus able to specify the network or networks the application is to use and, if more than one network is specified, in what order they are to be tried. These routines have the following syntax:

   #include <netconfig.h>
   
   void *
   setnetpath
   

   struct netconfig *
   getnetpath(handlep)
   void * handlep;
   

   int
   endnetpath(handlep)
   void * handlep;

A call to setnetpath has the effect of initializing NETPATH. It returns a pointer to a database that contains the entries specified in a NETPATH variable. The pointer, called a handle, is used when traversing this database with getnetpath. setnetpath must be called before the first call to getnetpath and may be called at any other time. setnetpath returns NULL if the netconfig database is not present. setnetpath takes no arguments.

When first called, getnetpath returns a pointer to the netconfig database entry that corresponds to the first component of the NETPATH variable (the instance described by the handle). NETPATH components are read from left to right. 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 component of the NETPATH variable. getnetpath returns NULL on end of file. A call to getnetpath without an initial call to setnetpath will produce an error. getnetpath takes a handle as an argument.

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 is called to free the database pointer to elements in the NETPATH variable when processing is complete. It returns 0 on success and -1 on failure. endnetpath will fail if setnetpath was not called previously. endnetpath takes the instance handlep as an argument:

void *handlep;

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

while ((netconfigp = getnetpath(handlep)) != NULL) {
	/*
	  *   netconfigp now describes a transport provider
	  */
}
endnetpath(handlep);

Sample Code Using setnetpath, getnetpath, and endnetpath