[ Next Article |
Previous Article |
Book Contents |
Library Home |
Legal |
Search ]
Communications Technical Reference, Volume 1
nis_remove_entry (NIS+ API)
Purpose
Used to remove an NIS+ object from the NIS+ table_name.
Syntax
cc [ flag . . . ] file. . . -lnsl [ library. . . ]
#include <rpcsvc/nis.h>
nis_result * nis_remove_entry(nis_name name, nis_object, *
object, u_long flags);
Description
One of a group of NIS+ APIs that is used to search and modify NIS+ tables,
nis_remove_entry( ) is used to remove the identified entry from the table or a set of entries
identified by table_name.
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
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.
To succeed, nis_remove_entry( ) must inherit the PAF_TRUSTED_PATH attribute.
Return Values
These 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( ).
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( ).
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( ).
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.
- zticks
- The time spent in the NIS+ service itself, this count starts when the server receives
the request and stops when it sends the reply.
- dticks
- The time spent in the database backend, this time is measured from the time a database
call starts until a result is returned. If the request results in multiple calls to the database,
this is the sum of all the time spent in those calls.
- aticks
- The time spent in any accelerators or caches. This includes the time required
to locate the server needed to resolve the request.
- cticks
- The total time spent in the request, this clock starts when you enter the client library
and stops when a result is returned. By subtracting the sum of the other ticks values from this
value you can obtain the local overhead of generating an NIS+ request.
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.
Errors
The client library can return a variety of error returns and diagnostics. Following are some of the
mor pertient ones:
- NIS_BADATTRIBUTE
- The name of an attribute did not match up with a named column in the table, or the attribute
did not have an associated value.
- NIS_BADNAME
- The name passed to the function is not a legal NIS+ name.
- NIS_BADREQUEST
- A problem was detected in the request structure passed to the client library.
- NIS_CACHEEXPIRED
- The entry returned came from an object cache that has expired.
This means that the time to live value has gone to zero and the entry may have changed.
If the flag NO_CACHE was passed to the lookup function, the lookup function will
retry the operation to get an unexpired copy of the object.
- NIS_CBERROR
- An RPC error occurred on the server while it was calling back to the client.
The transaction was aborted at that time and any unsent data was discarded.
- NIS_CBRESULTS
- Even though the request was successful, all of the entries have been sent to your
callback function and are thus not included in this result.
- NIS_FOREIGNNS
- The name could not be completely resolved. When the name passed to the function
would resolve in a namespace that is outside the NIS+ name tree, this error is returned
with a NIS+ object of type DIRECTORY. The returned object contains the type of
namespace and contact information for a server within that namespace.
- NIS_INVALIDOBJ
- The object pointed to by object is not a valid NIS+ entry object for
the given table. This could occur if it had a mismatched number of columns, or a different
data type (for example, binary or text) than the associated column in the table.
- NIS_LINKNAMEERROR
- The name passed resolved to a LINK type object and the contents of the
object pointed to an invalid name.
- NIS_MODFAIL
- The attempted modification failed.
- NIS_NAMEEXISTS
- An attempt was made to add a name that already exists. To add the name, first
remove the existing name and then add the new name or modify the existing named object.
- NIS_NAMEUNREACHABLE
- This soft error indicates that a server for the desired directory of the named table
object could not be reached. This can occur when there is a network partition or the server
has crashed. Attempting the operation again may succeed. See the
HARD_LOOKUP flag.
- NIS_NOCALLBACK
- The server was unable to contact the callback service on your machine. This results in
no data being returned.
- NIS_NOMEMORY
- Generally a fatal result. It means that the service ran out of heap space.
- NIS_NOSUCHNAME
- This hard error indicates that the named directory of the table object does not exist.
This occurs when the server that should be the parent of the server that serves the table
does not know about the directory in which the table resides.
- NIS_NOSUCHTABLE
- The named table does not exist.
- NIS_NOT_ME
- A request was made to a server that does not serve the given name. Normally, this will
not occur; however, if you are not using the built in location mechanism for servers, you
may see this if your mechanism is broken.
- NIS_NOTFOUND
- No entries in the table matched the search criteria. If the search criteria was null
(return all entries), then this result means that the table is empty and may safely be
removed by calling the nis_remove( ). If the FOLLOW_PATH flag was set,
this error indicates that none of the tables
in the path contain entries that match the search criteria.
- NIS_NOTMASTER
- A change request was made to a server that serves the name, but it is not the master
server. This can occur when a directory object changes and it specifies a new master server.
Clients that have cached copies of the directory object in the /var/nis/NIS_SHARED_DIRCACHE
file will need to have their cache managers restarted
(use nis_cachemgr -i to flush this cache).
- NIS_NOTSAMEOBJ
- An attempt to remove an object from the namespace was aborted because the object
that would have been removed was not the same object that was passed in the request.
- NIS_NOTSEARCHABLE
- The table name resolved to a NIS+ object that was not searchable.
- NIS_PARTIAL
- This result is similar to NIS_NOTFOUND except that it means the request
succeeded but resolved to zero entries. When this occurs, the server returns a copy
of the table object instead of an entry so that the client may then process the path
or implement some other local policy.
- NIS_RPCERROR
- This fatal error indicates the RPC subsystem failed in some way. Generally there
will be a syslog(3) message indicating why the RPC request failed.
- NIS_S_NOTFOUND
- The named entry does not exist in the table; however, not all tables in the path
could be searched, so the entry may exist in one of those tables.
- NIS_S_SUCCESS
- Even though the request was successful, a table in the search path was not able
to be searched, so the result may not be the same as the one you would have received
if that table had been accessible.
- NIS_SUCCESS
- The request was successful.
- NIS_SYSTEMERROR
- Some form of generic system error occurred while attempting the request. Check
the syslog(3) record for error messages from the server.
- NIS_TOOMANYATTRS
- The search criteria passed to the server had more attributes than the table
had searchable columns.
- NIS_TRYAGAIN
- The server connected to was too busy to handle your request.
add_entry( ), remove_entry( ), and modify_entry( ) return
this error when the master server is currently updating its internal state. It can
be returned to nis_list( ) when the function specifies a callback and the
server does not have the resources to handle callbacks.
- NIS_TYPEMISMATCH
- An attempt was made to add or modify an entry in a table, and the entry
passed was of a different type than the table.
Summary of Trusted
To succeed, nis_remove_entry( ) must inherit
the PAF_TRUSTED_PATH attribute.
Related Information
nis_add_entry,
nis_first_entry,
nis_list,
nis_local_directory,
nis_lookup,
nis_modify_entry,
nis_next_entry,
nis_perror, and
nis_sperror.
Network Information Services+ and
NIS+ Namespace and Structure
in AIX Version 4.3 Network Information Services (NIS and NIS+) Guide.
TCP/IP
Protocols in AIX Version 4.3 System Management Guide: Communications and Networks.
List of NIS and NIS+ Programming References
and Remote Procedure Call (RPC) Overview for
Programming in AIX Version 4.3 Communications Programming Concepts.
[ Next Article |
Previous Article |
Book Contents |
Library Home |
Legal |
Search ]