NAME

nis_misc, nis_mkdir, nis_rmdir, nis_servstate, nis_stats, nis_getservlist, nis_freeservlist, nis_freeresult, nis_freetags − miscellaneous NIS+ functions

SYNOPSIS

#include <rpcsvc/nis.h> #include <rpcsvc/nis_tags.h>

nis_error nis_mkdir(nis_name dirname, nis_server ∗machine);

nis_error nis_rmdir(nis_name dirname, nis_server ∗machine);

nis_error nis_servstate(nis_server ∗machine, nis_tag ∗tags, int numtags);

nis_error nis_stats(nis_server ∗machine, nis_tag ∗tags, int numtags);

void nis_freetags(nis_tag ∗tags, int numtags);

nis_server ∗∗nis_getservlist(nis_name dirname);

void nis_freeservlist(nis_server ∗∗machines);

void nis_freeresult(nis_result ∗result);

DESCRIPTION

These functions provide a variety of services for NIS+ applications. The first two, nis_mkdir() and nis_rmdir() are used to remotely create the necessary databases to support NIS+ service for a directory, dirname, on a server, machine. Before this operation can be successful, the directory object describing dirname must have been updated to reflect that server machine either is serving, or is no longer serving the named directory. 

The following functions, nis_servstate() and nis_stats() use the a tag list, tags, as a parameter. This tag list is a variable length array of nis_tag structures whose length is passed to the function in the numtags parameter.  The set of legal tags are defined in the file <rpcsvc/nis_tags.h> which is included automatically when you include <rpcsvc/nis.h> in your program.  Because these tags can and do vary between implementations of the NIS+ service, it is best to consult this file for the supported list.  Passing unrecognized tags to a server will result in their tag_value member being set to the string “unknown.” Both of these functions return their results in malloced tag structure.  The tag_value pointers points to allocated string memory which contains the results.  To free this string memory, you should call nis_freetags(). 

The function nis_servstate() is used to set and read the various state variables of the NIS+ servers.  In particular the internal debugging state and security levels of the servers may be queried, and in the former case set. 

The other use for the nis_servstate() function is to flush internal caches that are out of date.  The service maintains two caches to enhance performance, one for directory objects and the other for group objects.  Using the TAG_GCACHE and/or the TAG_DCACHE tags, will flush these caches.  The caches will normally expire objects when their time to live expires, however this function can be used to expedite the process. 

The nis_stats() function is used to retrieve statistics about how the server is operating.  This includes such information as the number of times the service had to refuse serving a client because it was too busy.  Tracking these statistics can help administrators determine when they need to add additional replicas or to break up a domain into two or more subdomains.  For more information on reading statistics see nisstat(1M), and the SunOS 5.1 Administering NIS+ and DNS guide.  Note: the service can disable the reporting of statistics (see rpc.nisd(1M)). 

The functions nis_getservlist() and nis_freeservlist() are complementary.  nis_getservlist() returns a null terminated list of nis_server structures that represent the list of servers that serve the domain named dirname. Servers from this list can be used when calling functions that require the name of a NIS+ server.  nis_freeservlist() frees the list of servers returned by nis_getservlist().  Note that this is the only legal way to free that list. 

The function nis_freeresult() frees all memory associated with a nis_result structure.  This function must be called to free the memory associated with a NIS+ result.  If one or more of the objects returned in the structure need to be retained, then can be copied with the nis_cloneobject() function (see nis_subr(3N)). 

SEE ALSO

nis_names(3N), nis_objects(3N), nis_subr(3N)

SunOS 5.1  —  Last change: 13 Oct 1991