|
|
HP-UX Reference > Nnis_tables(3N)HP-UX 11i Version 2: December 2007 Update |
|
NAMEnis_tables: nis_list(), nis_add_entry(), nis_remove_entry(), nis_modify_entry(), nis_first_entry(), nis_next_entry() — NIS+ table functions SYNOPSIScc [ flag... ] file... -lnsl [ library... ] #include <rpcsvc/nis.h> nis_result *nis_list(const nis_name name, const u_long flags, int (*callback)(const nis_name table_name, const nis_object *object, const void *userdata), const void *userdata)); nis_result *nis_add_entry(const nis_name table_name, const nis_object *object, const u_long flags); nis_result *nis_remove_entry(const nis_name name, const nis_object *object, const u_long flags); nis_result *nis_modify_entry(const nis_name name, const nis_object *object, const u_long flags); nis_result *nis_first_entry(const nis_name table_name); nis_result *nis_next_entry(const nis_name table_name, const netobj *cookie); void nis_freeresult(nis_result *result); DESCRIPTIONThese functions are used to search and modify NIS+ tables. nis_list() is used to search a table in the NIS+ namespace. nis_first_entry() and nis_next_entry() are used to enumerate a table one entry at a time. nis_add_entry(), nis_remove_entry(), and nis_modify_entry() are used to change the information stored in a table. nis_freeresult() is used to free the memory associated with the nis_result structure. Entries within a table are named by NIS+ indexed names. An indexed name is a compound name that is composed of a search criteria and a simple NIS+ name that identifies a table object. A search criteria is a series of column names and their associated values enclosed in bracket `[]' characters. Indexed names have the following form: [ colname=value, ... ],tablename The list function, nis_list(), takes an indexed name as the value for the name parameter. Here, the tablename should be a fully qualified NIS+ name unless the EXPAND_NAME flag (described below) is set. The second parameter, flags, defines how the function will respond to various conditions. The value for this parameter is created by logically ORing together one or more flags from the following list.
The third parameter to nis_list(), callback, is an optional pointer to a function that will process the ENTRY type objects that are returned from the search. If this pointer is NULL, then all entries that match the search criteria are returned in the nis_result structure, otherwise this function will be called once for each entry returned. When called, this function should return 0 when additional objects are desired and 1 when it no longer wishes to see any more objects. The fourth parameter, userdata, is simply passed to callback function along with the returned entry object. The client can use this pointer to pass state information or other relevant data that the callback function might need to process the entries. nis_add_entry() will add the NIS+ object to the NIS+ table_name. The flags parameter is used to specify the failure semantics for the add operation. The default (flags equal 0) is to fail if the entry being added already exists in the table. The ADD_OVERWRITE flag may be used to specify that the existing object is to be overwritten if it exists, (a modify operation) or added if it does not exist. With the ADD_OVERWRITE flag, this function will fail with the error NIS_PERMISSION if the existing object does not allow modify privileges to the client. If the flag RETURN_RESULT has been specified, the server will return a copy of the resulting object if the operation was successful. nis_remove_entry() removes the identified entry from the table or a set of entries identified by table_name. If the parameter object is non-null, it is presumed to point to a cached copy of the entry. When the removal is attempted, and the object that would be removed is not the same as the cached object pointed to by object then the operation will fail with an NIS_NOTSAMEOBJ error. If an object is passed with this function, the search criteria in name is optional as it can be constructed from the values within the entry. However, if no object is present, the search criteria must be included in the name parameter. If the flags variable is null, and the search criteria does not uniquely identify an entry, the NIS_NOTUNIQUE error is returned and the operation is aborted. If the flag parameter REM_MULTIPLE is passed, and if remove permission is allowed for each of these objects, then all objects that match the search criteria will be removed. Note that a null search criteria and the REM_MULTIPLE flag will remove all entries in a table. nis_modify_entry() modifies an object identified by name. The parameter object should point to an entry with the EN_MODIFIED flag set in each column that contains new information. These columns will replace their counterparts in the entry that is stored in the table. The entry passed must have the same number of columns, same type, and valid data in the modified columns for this operation to succeed. If the flags parameter contains the flag MOD_SAMEOBJ then the object pointed to by object is assumed to be a cached copy of the original object. If the OID of the object passed is different than the OID of the object the server fetches, then the operation fails with the NIS_NOTSAMEOBJ error. This can be used to implement a simple read-modify-write protocol which will fail if the object is modified before the client can write the object back. If the flag RETURN_RESULT has been specified, the server will return a copy of the resulting object if the operation was successful. nis_first_entry() fetches entries from a table one at a time. This mode of operation is extremely inefficient and callbacks should be used instead wherever possible. The table containing the entries of interest is identified by name. If a search criteria is present in name it is ignored. The value of cookie within the nis_result structure must be copied by the caller into local storage and passed as an argument to nis_next_entry(). nis_next_entry() retrieves the next entry from a table specified by table_name. The order in which entries are returned is not guaranteed. Further, should an update occur in the table between client calls to nis_next_entry() there is no guarantee that an entry that is added or modified will be seen by the client. Should an entry be removed from the table that would have been the next entry returned, the error NIS_CHAINBROKEN is returned instead. MULTITHREAD USAGE
These functions can be called safely in a multithreaded environment. These functions may be thread cancellation points because they invoke functions that are thread cancellation points. In a multithreaded environment, these functions are not safe to be called by a child process after fork() and before exec(). These functions should not be called by a multithreaded application that support asynchronous cancellation or asynchronous signals. RETURN VALUEThese functions return a pointer to a structure of type nis_result: struct nis_result { nis_error status; struct { u_int objects_len; nis_object *objects_val; } objects; netobj cookie; u_long zticks; u_long dticks; u_long aticks; u_long cticks; }; The status member contains the error status of the the operation. A text message that describes the error can be obtained by calling the function nis_sperrno() (see nis_error(3N)). The objects structure contains two members. objects_val is an array of nis_object structures; objects_len is the number of cells in the array. These objects will be freed by a call to nis_freeresult() (see nis_names(3N)). If you need to keep a copy of one or more objects, they can be copied with the function nis_clone_object() and freed with the function nis_destroy_object() (see nis_server(3N)). The various ticks contain details of where the time (in microseconds) was taken during a request. They can be used to tune one's data organization for faster access and to compare different database implementations (see nis_db(3N)).
Subtracting the value in dticks from the value in zticks will yield the time spent in the service code itself. Subtracting the sum of the values in zticks and aticks from the value in cticks will yield the time spent in the client library itself. Note: all of the tick times are measured in microseconds. ERRORSThe client library can return a variety of error returns and diagnostics. The more salient ones are documented below.
WARNINGSUse the flag HARD_LOOKUP carefully since it can cause the application to block indefinitely during a network partition. HP-UX 11i Version 2 is the last HP-UX release on which NIS+ is supported. LDAP is the recommended replacement for NIS+. HP fully supports the industry standard naming services based on LDAP. NOTESThe path used when the flag FOLLOW_PATH is specified, is the one present in the first table searched. The path values in tables that are subsequently searched are ignored. It is legal to call functions that would access the nameservice from within a list callback. However, calling a function that would itself use a callback, or calling nis_list() with a callback from within a list callback function is not currently supported. There are currently no known methods for nis_first_entry() and nis_next_entry() to get their answers from only the master server. |
|