Man Pages

---

Back to Software Index  Manpage Top Level

Name

Synopsis

#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);

MT-Level

Description

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 during the enumeration. This may be invoked at any time to terminate the enumeration.

Return Values

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

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 continued.

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 functions set status for these other status codes as described in FN_status_t(3N) and xfn_status_codes(3N) .

Usage

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 implementations 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() should not be invoked on ctx until the enumeration has terminated.

Examples

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’ */

See Also

Notes

Table of Contents

• Name
• Synopsis
• MT-Level
• Description
• Return Values
• Errors
• Usage
• Examples
• See Also
• Notes