nis_server(3N)

NAME

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

SYNOPSIS

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

nis_error nis_mkdir(const nis_name dirname, const nis_server ∗machine);

nis_error nis_rmdir(const nis_name dirname, const nis_server ∗machine);

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

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

void nis_freetags(nis_tag ∗tags, const int numtags);

nis_server ∗∗nis_getservlist(const nis_name dirname);

void nis_freeservlist(nis_server ∗∗machines);

void nis_freeresult(nis_result ∗result);

MT-LEVEL

Unsafe

DESCRIPTION

These functions provide a variety of services for NIS+ applications. nis_mkdir() is used to create the necessary databases to support NIS+ service for a directory, dirname, on a server, machine. If this operation is successful, it means that the directory object describing dirname has been updated to reflect that server machine is serving the named directory.

nis_rmdir() is used to delete the directory from the specified machine. The machine parameter cannot be NULL. For a description of the nis_server structure, refer to nis_objects(3N).

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 set and queried.

The other use for nis_servstate() 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. Normally, the caches will expire objects when their time to live expires, but 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).

nis_servstate() and nis_stats() use the tag list. 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 with <rpcsvc/nis.h>. 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, ∗result. If there is an error, ∗result is set to NULL. The tag_value pointers points to allocated string memory which contains the results. Use nis_freetags() to free this string memory.

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.

NOTES

These interfaces are unsafe in multithreaded applications. Unsafe interfaces should be called only from the main thread.

SunOS 5.2 — Last change: 22 Jan 1993

Museum