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

man pages section 3: Networking Library Functions

fn_composite_name_first(3XFN)

NAME

FN_composite_name_t, fn_composite_name_create, fn_composite_name_destroy, fn_composite_name_from_str, fn_composite_name_from_string, fn_string_from_composite_name, fn_composite_name_copy, fn_composite_name_assign, fn_composite_name_is_empty, fn_composite_name_count, fn_composite_name_first, fn_composite_name_next, fn_composite_name_prev, fn_composite_name_last, fn_composite_name_prefix, fn_composite_name_suffix, fn_composite_name_is_equal, fn_composite_name_is_prefix, fn_composite_name_is_suffix, fn_composite_name_prepend_comp, fn_composite_name_append_comp, fn_composite_name_insert_comp, fn_composite_name_delete_comp, fn_composite_name_prepend_name, fn_composite_name_append_name, fn_composite_name_insert_name– a sequence of component names spanning multiple naming systems

SYNOPSIS

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

name

cstr

str

name

status

name

dst

src

name

iter_pos

name

iter_pos

name

iter_pos

name

iter_pos

name

iter_pos

name

iter_pos

name

name2

status

name

prefix

iter_pos

status

name

suffix

iter_pos

status

name

newcomp

name

newcomp

name

iter_pos

newcomp

name

iter_pos

name

newcomps

name

newcomps

name

iter_pos

newcomps

DESCRIPTION

A composite name is represented by an object of type FN_composite_name_t. Each component is a string name, of type FN_string_t, from the namespace of a single naming system. It may be an atomic name or a compound name in that namespace.

fn_composite_name_create creates an FN_composite_name_t object with zero components. Components may be subsequently added to the composite name using the modify operations described below. fn_composite_name_destroy releases any storage associated with the given FN_composite_name_t handle.

fn_composite_name_from_str() creates an FN_composite_name_t from the given null-terminated string based on the code set of the current locale setting, using the XFN composite name syntax. fn_composite_name_from_string() creates an FN_composite_name_t from the string str using the XFN composite name syntax. fn_string_from_composite_name() returns the standard string form of the given composite name, by concatenating the components of the composite name in a left to right order, each separated by the XFN component separator.

fn_composite_name_copy() returns a copy of the given composite name object. fn_composite_name_assign() makes a copy of the composite name object pointed to by src and assigns it to dst, releasing any old contents of dst. A pointer to the same object as dst is returned.

fn_composite_name_is_empty() returns 1 if the given composite name is an empty composite name (that is, it consists of a single, empty component name); otherwise, it returns 0. fn_composite_name_count() returns the number of components in the given composite name.

The iteration scheme is based on the exchange of an opaque void * argument, iter_pos, that serves to record the position of the iteration in the sequence. Conceptually, iter_pos records a position between two successive components (or at one of the extreme ends of the sequence).

The function fn_composite_name_first() returns a handle to the FN_string_t that is the first component in the name, and sets iter_pos to indicate the position immediately following the first component. It returns 0 if the name has no components. Thereafter, successive calls of the fn_composite_name_next() function return pointers to the component following the iteration marker, and advance the iteration marker. If the iteration marker is at the end of the sequence, fn_composite_name_next() returns 0. Similarly, fn_composite_name_prev() returns the component preceding the iteration pointer and moves the marker back one component. If the marker is already at the beginning of the sequence, fn_composite_name_prev() returns 0. The function fn_composite_name_last() returns a pointer to the last component of the name and sets the iteration marker immediately preceding this component (so that subsequent calls to fn_composite_name_prev() can be used to step through leading components of the name).

The fn_composite_name_suffix() function returns a composite name consisting of a copy of those components following the supplied iteration marker. The method fn_composite_name_prefix() returns a composite name consisting of those components that precede the iteration marker. Using these functions with an iteration marker that was not initialized using fn_composite_name_first(), fn_composite_name_last(), fn_composite_name_is_prefix(), or fn_composite_name_is_suffix() yields undefined and generally undesirable behavior.

The functions fn_composite_name_is_equal(), fn_composite_name_is_prefix(), and fn_composite_name_is_suffix() test for equality between composite names or between parts of composite names. For these functions, equality is defined as exact string equality, not name equivalence. A name's syntactic property, such as case-insensitivity, is not taken into account by these functions.

The function fn_composite_name_is_prefix() tests if one composite name is a prefix of another. If so, it returns 1 and sets the iteration marker immediately following the prefix. (For example, a subsequent call to fn_composite_name_suffix() will return the remainder of the name.) Otherwise, it returns 0 and the value of the iteration marker is undefined. The function fn_composite_name_is_suffix() is similar. It tests if one composite name is a suffix of another. If so, it returns 1 and sets the iteration marker immediately preceding the suffix.

The functions fn_composite_name_prepend_comp() and fn_composite_name_append_comp() prepend and append a single component to the given composite name, respectively. These operations invalidate any iteration marker the client holds for that object. fn_composite_name_insert_comp() inserts a single component before iter_pos to the given composite name and sets iter_pos to be immediately after the component just inserted. fn_composite_name_delete_comp() deletes the component located before iter_pos from the given composite name and sets iter_pos back one component.

The functions fn_composite_name_prepend_name(), fn_composite_name_append_name(), and fn_composite_name_insert_name() perform the same update functions as their _comp counterparts, respectively, except that multiple components are being added, rather than single components. For example, fn_composite_name_insert_name() sets iter_pos to be immediately after the name just added.

RETURN VALUES

The functions fn_composite_name_is_empty(), fn_composite_name_is_equal(), fn_composite_name_is_suffix(), and fn_composite_name_is_prefix() return 1 if the test indicated is true; 0 otherwise.

The update functions fn_composite_name_prepend_comp(), fn_composite_name_append_comp(), fn_composite_name_insert_comp(), fn_composite_name_delete_comp(), and their _name counterparts return 1 if the update was successful; 0 otherwise.

If a function is expected to return a pointer to an object, a NULL pointer (0) is returned if the function fails.

ERRORS

Code set mismatches that occur during the composition of the string form or during comparisons of composite names are resolved in an implementation-dependent way. fn_string_from_composite_name(), fn_composite_name_is_equal(), fn_composite_name_is_suffix(), and fn_composite_name_is_prefix() set status to FN_E_INCOMPATIBLE_CODE_SETS for composite names whose components have code sets that are determined by the implementation to be incompatible.

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.8 Last Revised 13 Dec 1996