NETINFO(3N)NETINFO(3N)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 {
int rtimeout;
int wtimeout;
int abort;
int needwrite;
} 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.
NeXT Computer, Inc. August 29, 1989 NETINFO(3N)