FN_namelist_t(3XFN) (man pages section 3: Networking Library Functions)

man pages section 3: Networking Library Functions

FN_namelist_t(3XFN)

NAME

fn_ctx_list_names, FN_namelist_t, fn_namelist_next, fn_namelist_destroy- list the atomic names bound in a context

SYNOPSIS

cc [ flag ... ] file ... -lxfn [ library ... ]
#include <xfn/xfn.h>

ctx

name

status

nl

status

nl

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

RETURN VALUES

fn_ctx_list_names() returns a pointer to an FN_namelist_t object if the enumeration is successfully initiated; otherwise 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 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(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 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(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 attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe

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.

SunOS 5.9 Last Revised 13 Dec 1996