Manpages

NAME

netinfo − library routines for NetInfo calls

SYNOPSIS

#include <netinfo/ni.h>

DESCRIPTION

These calls are the programming interface to NetInfo. Typically, a handle (of type "void *") is allocated through a call to ni_new, ni_open, or ni_connect. This handle opens a connection to the given NetInfo domain. Read calls may go to either the master or the clone servers, while writes will always go to the master server. If the master is unavailable, no writes can be performed. The handle is then passed to one of several NetInfo routines for database operations and then freed using ni_free. Several utility routines are also supplied which operate on NetInfo data structures. These routines don’t require NetInfo handles.

MACROS

NI_INDEX_NULL

A constant which evaluates to the highest unsigned integer. It is useful for indicating something which should go at the end of a list, as opposed to a smaller value which indicates the precise position at which the insert should occur.

NI_INIT(ptr)

Initializes a NetInfo data structure. It effectively zeros out the structure referred to by ptr. This macro is useful for indicating an empty list or NULL value with one of the many NetInfo data structures.

DATATYPES AND ASSOCIATED UTILITY ROUTINES

ni_status

The result code of most NetInfo routines.

const char *ni_error(ni_status status)

Returns the error string associated with the given NetInfo status.

ni_index

An index into a NetInfo list.

ni_id

NetInfo directories are identified through the ni_id data structure. It records the ID of the directory in the nii_object field and the instance of the directory in the nii_instance field. The instance indicates which version of the directory is being operated on and is only relevant for writes. Each time a write is performed, the instance is incremented to reflect the new version. If the instance given does not match the current instance of the directory, the error NI_STALE is returned, indicating a stale ID. All NetInfo routines which operate on directories will return the latest value of the instance.

ni_name

A NetInfo name. It is equivalent to a C string.

ni_name ni_name_dup(const ni_name name)

Returns a mallocated copy of a NetInfo name.

void ni_name_free(ni_name *namep)

Frees a NetInfo name. The pointer is converted to NULL. A NULL pointer will not be freed.

int ni_name_match(const ni_name name1, const ni_name name2)

Compares two NetInfo names for equality. Returns non-zero for success, zero for failure.

ni_namelist

A list of NetInfo names.

ni_namelist ni_namelist_dup(const ni_namelist nl)

Returns a mallocated duplicate of a NetInfo namelist.

void ni_namelist_free(ni_namelist *nl)

Frees a NetInfo namelist. The namelist structure is zeroed. Zeroed namelists will not be freed.

void ni_namelist_insert(ni_namelist *nl, const ni_name name, ni_index where)

Duplicates and inserts the given name at the given location into the namelist.

void ni_namelist_delete(ni_namelist *nl, ni_index where)

Deletes and frees the name at the given location in the namelist.

ni_index ni_namelist_match(const ni_namelist nl, const ni_name name)

If the name is in the given namelist, the first index of its occurrence is returned. Otherwise, NI_INDEX_NULL is returned indicating failure.

ni_property

A NetInfo property. It contains a name and a namelist of associated values.

ni_property ni_prop_dup(const ni_property prop)

Returns a mallocated duplicate of the given NetInfo property.

void ni_prop_free(ni_property *prop)

Frees and zeros the NetInfo property. Zeroed properties will not be freed again.

ni_proplist

A list of NetInfo properties.

void ni_proplist_insert(ni_proplist *pl, const ni_property prop, ni_index where)

Duplicates and inserts the given property at the given location into the given property list.

void ni_proplist_delete(ni_proplist *pl, ni_index where)

Frees and deletes the property at the given location in the property list.

ni_index ni_proplist_match(const ni_proplist pl, const ni_name name, const ni_name val)

Returns the location in the property list of the first property with a name of name and having value val. NI_INDEX_NULL is returned on failure. If NULL is the value argument, ni_proplist_match will match on only the name argument.

ni_proplist ni_proplist_dup(const ni_proplist pl)

Returns a mallocated duplicate property list.

void ni_proplist_free(ni_proplist *pl)

Frees and zeroes the property list. A zeroed property will not be freed again.

ni_idlist

A list of NetInfo indices (usually directory ID’s).

void ni_idlist_free(ni_idlist *idl)

Frees and zeroes the given ID list. A zeroed ID list will not be freed again.

ni_entry

An entry in a NetInfo directory. It contains the ID of the directory and a list of values assocated with whatever property was requested in the ni_list routine. The list may be NULL, indicating that there is not associated property for this directory.

ni_entrylist

A list of NetInfo entries.

void ni_entrylist_free(ni_entrylist *entries)

Frees and zeros the given entry list. A zeroed entry list will not be freed again.

ROUTINES

ni_status ni_addrtag(void *handle, struct sockaddr_in *addr, ni_name *tag)

Returns the address and domain tag associated with the connected NetInfo handle.

ni_status ni_children(void *handle, ni_id *dir, ni_idlist *idlist)

Lists the children ID’s (subdirectories) of the given directory.

void *ni_connect(struct sockaddr_in *addr, ni_name tag)

Returns a NetInfo handle to the NetInfo domain at the given address and domain tag. Returns NULL on failure.

ni_status ni_create(void *handle, ni_id *parent, ni_proplist props, ni_id *child, ni_index where)

Creates a new directory at the given index initialized with the given properties.

ni_status ni_createname(void *handle, ni_id *dir, ni_index prop_index, ni_name name, ni_index val_index)

Inserts the name into the value list of the given directory at the property indexed by prop_index and value list location val_index.

ni_status ni_createprop(void *handle, ni_id *dir, ni_property prop, ni_index where)

Creates a new property at the given index in the given directory.

ni_status ni_destroy(void *handle, ni_id *parent, ni_id child)

Destroys the directory child in the given parent directory. Both instance must be the latest values or the error NI_STALE is returned.

ni_status ni_destroyname(void *handle, ni_id *dir, ni_index prop_index, ni_index val_index)

Destroys a property value in the given directory at the given prop_index and value-list val_index.

ni_status ni_destroyprop(void *handle, ni_id *dir, ni_index where)

Destroys the property at property index where in the given directory.

ni_status ni_fancyopen(void *handle, ni_name domain, void **rethandle, ni_fancyopenargs *args)

typedef struct ni_fancyopenargs {

} ni_fancyopenargs;

A fancier version of ni_open which allows one to set various attributes on the the returned handle. See ni_setreadtimeout(), ni_setwritetimeout(), ni_setabort() and ni_needwrite() for descriptions of the fields in the ni_fancyopenargs structure. A 0 in the rtimeout or wtimeout field indicates the default timeout should be used.

void ni_free(void *handle)

Frees a NetInfo handle and closes any associated connections.

ni_status ni_list(void *handle, ni_id *dir , ni_name name, ni_entrylist *entries)

Lists all the subdirectories of the given directory along with any associated values they may have for the property name. If a subdirectory doesn’t have the property name, the entry is still returned but with a NULL property list.

ni_status ni_listprops(void *handle, ni_id *dir, ni_namelist *nl)

Returns the list of property names associated with the given directory.

ni_status ni_lookup(void *handle, ni_id *dir, ni_name name, ni_name val, ni_idlist *found)

Returns a list of subdirectories which satisfy the relation name equals val.

ni_status ni_lookupprop(void *handle, ni_id *dir, ni_name name, ni_namelist *val)

Returns the values associated with the property named name in the given directory.

ni_status ni_lookupread(void *handle, ni_id *dirid, ni_name propname, ni_name propval, ni_proplist *props)

Looks up the subdirectory given the (propname, propval pair and returns the subdirectory’s properties. This call is equivalent to an ni_lookup() followed by an ni_read().

void ni_needwrite(void *handle, int needwrite)

Indicates whether subsequent calls will need to write to a netinfo server. By default, the flag is off and the netinfo library will automatically switch to a server capable of writing whenever a write call occurs. However, since writes may take some time to reach the clone server, one could read stale information from a clone server and then attempt to write the master based upon the stale information. Setting needwrite will lock the handle onto the master netinfo server even for reads to prevent this from happening.

ni_status ni_open(void *relativeto, ni_name domain, void **result)

Opens a connection to the NetInfo domain domain. The returned handle is opened relative to the domain specified in the relativeto. This handle may be passed as NULL, indicating relative to the local NetInfo domain. The path may contain "/"s to indicate a multilevel search and may also be "." or ".." to indicate the current domain or parent domain, respectively.

ni_status ni_parent(void *handle, ni_id *dir, ni_index *parent_id)

Returns the parent ID of the given directory.

ni_status ni_pathsearch(void *handle, ni_id *dir, ni_name path)

Does a multilevel lookup on a directory, relative to the given directory ID. The path may contain "/"s to separative directory components. "="s are used to specify relations and both may be escaped using "\"s. For example, to find the directory associated with the superuser, you may specify (relative to the root directory) "/name=users/uid=0". Note that the equal signs are not mandatory and will default to "name=" if none are specified. In the previous example, "/users/uid=0" would accomplish the same result.

ni_status ni_read(void *handle, ni_id *dir, ni_proplist *props)

Reads all of the properties of the given directory.

ni_status ni_readname(void *handle, ni_id *dir, ni_index prop_index, ni_index val_index, ni_name *value)

Reads a value from a property in the given directory. The value is indexed by property index prop_index and value index val_index.

ni_status ni_readprop(void *handle, ni_id *dir, ni_index prop_index, ni_namelist *nl)

Reads the value-list associated with the given property, indexed by prop_index.

ni_status ni_renameprop(void *handle, ni_id *dir, ni_index prop_index, ni_name newname)

Renames the property indexed by prop_index to the new name newname.

ni_status ni_resync(void *handle)

Attempts to resynchronize the clone servers with the master copy of the database.

ni_status ni_root(void *handle, ni_id *dir)

Returns the directory ID of the root of the directory tree.

ni_status ni_self(void *handle, ni_id *dir)

Returns the directory ID of the given directory. Simply refreshes the instance field to the latest value.

void ni_setabort(void *handle, int shouldabort)

By default, netinfo calls will try forever until an answer is returned from a server. ni_setabort
allows one to have netinfo return failure upon the first timeout or other failure.

ni_status ni_setpassword(void *handle, ni_name password)

Sets the password for the session to password. By default, no password is sent.

void ni_setreadtimeout(void *handle, int seconds)

Sets the timeout associated with reads on netinfo. The timeout is only a hint and the effective timeout may be longer. Note that calls will not abort even if a timeout is set unless the abort flag has been set (see ni_setabort()).

ni_status ni_setuser(void *handle, ni_name username)

Changes the username associated with the session. By default, the username is the one associated with the user-ID that was used during the UNIX login process.

void ni_setwritetimeout(void *handle, int seconds)

Sets the timeout associated with writes on netinfo. The timeout is only a hint and the effective timeout may be a longer. Note that calls will not abort even if a timeout is set unless the abort flag has been set (see ni_setabort()).

ni_status ni_statistics(void *handle, ni_proplist *statistics)

Returns various statistics from the server.

ni_status ni_write(void *handle, ni_id *dir, ni_proplist props)

Writes a new property list to the directory.

ni_status ni_writename(void *handle, ni_id *dir, ni_index prop_index, ni_index name_index, ni_name val)

Writes a new property value to the property indexed by prop_index and value indexed by val_index.

ni_status ni_writeprop(void *handle, ni_id *dir, ni_index prop_index, ni_namelist values)

Writes a new value list to the property indexed by prop_index. It is allowable to have more than one property with the same name.