Sun Microsystems, Inc.
spacerspacer
spacer   www.sun.com docs.sun.com | | |  
spacer
black dot
   
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
    
 
XFN Interface Library Functionsfn_ctx_list_names(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>
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 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 TYPEATTRIBUTE VALUE
MT-LevelMT-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.


SunOS 5.9Go To TopLast Changed 13 Dec 1996

 
      
      
Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.