Purpose
Used to modify
an NIS+ object identified
by name.
Syntax
cc [ flag .
. . ] file. . . -lnsl [ library.
. . ]
nis_remove_entry
* 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_modify_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_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.
The owner, group, and access rights of an
entry are modified by placing the modified information into the respective
fields of the parameter, object: zo_owner, zo_group,
and zo_access.
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, 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
that 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.
To succeed, nis_modify_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 more pertinent 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_modify_entry( ) must inherit the PAF_TRUSTED_PATH attribute.