An XFN reference is represented by the type FN_ref_t. An object of this type contains a reference type and a list of addresses. The ordering in this list at the time of binding might not be preserved when the reference is returned upon lookup.

The reference type is represented by an object of type FN_identifier_t. The reference type is intended to identify the class of object referenced. XFN does not dictate the precise use of this.

Each address is represented by an object of type FN_ref_addr_t.

fn_ref_create() creates a reference with no address, using ref_type as its reference type. Addresses can be added later to the reference using the functions described below. fn_ref_destroy() releases the storage associated with ref. fn_ref_copy() creates a copy of ref and returns it. fn_ref_assign() creates a copy of src and assigns it to dst, releasing any old contents of dst. A pointer to the same object as dst is returned.

fn_ref_addrcount() returns the number of addresses in the reference ref.

fn_ref_first() returns the first address in ref and sets iter_pos to be after the address. It returns 0 if there is no address in the list. fn_ref_next() returns the address following iter_pos in ref and sets iter_pos to be after the address. If the iteration marker iter_pos is at the end of the sequence, fn_ref_next() returns 0.

fn_ref_prepend_addr() adds addr to the front of the list of addresses in ref. fn_ref_append_addr() adds addr to the end of the list of addresses in ref. fn_ref_insert_addr() adds addr to ref before iter_pos and sets iter_pos to be immediately after the new reference added. fn_ref_delete_addr() deletes the address located before iter_pos in the list of addresses in ref and sets iter_pos back one address. fn_ref_delete_all () deletes all addresses in ref.

fn_ref_create_link() creates a reference using the given composite name link_name as an address. fn_ref_is_link() tests if ref is a link. It returns 1 if it is; 0 if it is not. fn_ref_link_name() returns the composite name stored in a link reference. It returns 0 if link_ref is not a link.

fn_ref_description() returns a string description of the given reference. It takes as argument an integer, detail, and a pointer to an integer, more_detail. detail specifies the level of detail for which the description should be generated; the higher the number, the more detail is to be provided. If more_detail is 0, it is ignored. If more_detail is non-zero, it is set by the description operation to indicate the next level of detail available, beyond that specified by detail. If no higher level of detail is available, more_detail is set to detail.

The following operations return 1 if the operation succeeds, 0 if the operation fails:

fn_ref_prepend_addr()

fn_ref_append_addr()

fn_ref_insert_addr()

fn_ref_delete_addr()

fn_ref_delete_all()

The reference type is intended to identify the class of object referenced. XFN does not dictate the precise use of this.

Multiple addresses in a single reference are intended to identify multiple communication endpoints for the same conceptual object. Multiple addresses may arise for various reasons, such as the object offering interfaces over more than one communication mechanism.

The client must interpret the contents of a reference based on the type of the addresses and the type of the reference. However, this interpretation is intended to occur below the application layer. Most applications developers should not have to manipulate the contents of either address or reference objects themselves. These interfaces would generally be used within service libraries.

Manipulation of references using the operations described in this manual page does not affect their representation in the underlying naming system. Changes to references in the underlying naming system can only be effected through the use of the interfaces described in FN_ctx_t(3XFN).

See attributes(5) for descriptions of the following attributes:

FN_composite_name_t(3XFN), FN_ctx_t(3XFN), FN_identifier_t(3XFN), FN_ref_addr_t(3XFN), FN_string_t(3XFN), fn_ctx_lookup(3XFN), fn_ctx_lookup_link(3XFN), xfn(3XFN), xfn_links(3XFN), attributes(5)

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.