Партнёры:
Хостинг:
NAME
fn_ctx_list_names, FN_namelist_t, fn_namelist_next,
fn_namelist_destroy - list the atomic names bound in a con-
text
SYNOPSIS
cc [ flag ... ] file ... -lxfn [ library ... ]
#include <xfn/xfn.h>
FN_namelist_t *fn_ctx_list_names(FN_ctx_t *ctx, const
FN_composite_name_t *name, FN_status_t *status);
FN_string_t *fn_namelist_next(FN_namelist_t *nl, FN_status_t
*status);
void fn_namelist_destroy(FN_namelist_t *nl, FN_status_t
*status);
DESCRIPTION
This set of operations is used to list the names bound in
the target context named name relative to the context ctx.
Note that name must name a context. If the intent is to
list the contents of ctx, name should be an empty composite
name.
The call to fn_ctx_list_names() initiates the enumeration
process. It returns a handle to an FN_namelist_t object that
can be used to enumerate the names in the target context.
The operation fn_namelist_next() returns the next name in
the enumeration identified by nl and updates nl to indicate
the state of the enumeration. Successive calls to
fn_namelist_next() using nl return successive names in the
enumeration and further update the state of the enumeration.
fn_namelist_next() returns a NULL pointer (0) when the
enumeration has been completed.
fn_namelist_destroy() is used to release resources used dur-
ing the enumeration. This may be invoked at any time to ter-
minate the enumeration.
RETURN VALUES
fn_ctx_list_names() returns a pointer to an FN_namelist_t
object if the enumeration is successfully initiated; other-
wise it returns a NULL pointer (0).
fn_namelist_next() returns a NULL pointer (0) if no more
names can be returned in the enumeration.
In the case of a failure, these operations return in status
a code indicating the nature of the failure.
ERRORS
Each successful call to fn_namelist_next() returns a name
and sets status to FN_SUCCESS.
When fn_namelist_next() returns a NULL pointer (0), it
indicates that no more names can be returned. status is set
in the following way:
FN_SUCCESS
The enumeration has completed successfully.
FN_E_INVALID_ENUM_HANDLE
The supplied enumeration handle is not valid. Possible
reasons could be that the handle was from another
enumeration, or the context being enumerated no longer
accepts the handle (due to such events as handle
expiration or updates to the context).
FN_E_PARTIAL_RESULT
The enumeration is not yet complete but cannot be con-
tinued.
Other status codes, such as FN_E_COMMUNICATION_FAILURE, are
also possible in calls to fn_ctx_list_names(),
fn_namelist_next(), and fn_namelist_destroy(). These func-
tions set status for these other status codes as described
in FN_status_t(3XFN) and xfn_status_codes(3XFN).
USAGE
The names enumerated using fn_namelist_next() are not
ordered in any way. There is no guaranteed relation between
the order in which names are added to a context and the
order of names obtained by enumeration. The specification
does not guarantee that any two series of enumerations will
return the names in the same order.
When a name is added to or removed from a context, this may
or may not invalidate the enumeration handle that the
client holds for that context. If the enumeration handle
becomes invalid, the status code FN_E_INVALID_ENUM_HANDLE is
returned in status. If the enumeration handle remains
valid, the update may or may not be visible to the client.
In addition, there may be a relationship between the ctx
argument supplied to fn_ctx_list_names() and the
FN_namelist_t object it returns. For example, some imple-
mentations may store the context handle ctx within the
FN_namelist_t object for subsequent fn_namelist_next()
calls. In general, a fn_ctx_handle_destroy(3XFN) should not
be invoked on ctx until the enumeration has terminated.
EXAMPLES
Example 1: A sample program.
The following code fragment illustrates how the list names
operations may be used:
extern FN_string_t *user_input;
FN_ctx_t *ctx;
FN_composite_name_t *target_name = fn_composite_name_from_string(user_input);
FN_status_t *status = fn_status_create();
FN_string_t *name;
FN_namelist_t *nl;
ctx = fn_ctx_handle_from_initial(status);
/* error checking on 'status' */
if ((nl=fn_ctx_list_names(ctx, target_name, status)) == 0) {
/* report 'status' and exit */
}
while (name=fn_namelist_next(nl, status)) {
/* do something with 'name' */
fn_string_destroy(name);
}
/* check 'status' for reason for end of enumeration and report if necessary */
/* clean up */
fn_namelist_destroy(nl, status);
/* report 'status' */
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
FN_composite_name_t(3XFN), FN_ctx_t(3XFN),
FN_status_t(3XFN), FN_string_t(3XFN),
fn_ctx_handle_destroy(3XFN), xfn(3XFN),
xfn_status_codes(3XFN), attributes(5)
NOTES
The implementation of XFN in this Solaris release is based
on the X/Open preliminary specification. It is likely that
there will be minor changes to these interfaces to reflect
changes in the final version of this specification. The next
minor release of Solaris will offer binary compatibility for
applications developed using the current interfaces. As the
interfaces evolve toward standardization, it is possible
that future releases of Solaris will require minor source
code changes to applications that have been developed
against the preliminary specification.
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |