fn_ref_create(3XFN)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | USAGE | ATTRIBUTES | SEE ALSO | NOTES

NAME

FN_ref_t, fn_ref_create, fn_ref_destroy, fn_ref_copy, fn_ref_assign, fn_ref_type, fn_ref_addrcount, fn_ref_first, fn_ref_next, fn_ref_prepend_addr, fn_ref_append_addr, fn_ref_insert_addr, fn_ref_delete_addr, fn_ref_delete_all, fn_ref_create_link, fn_ref_is_link, fn_ref_link_name, fn_ref_description– an XFN reference

SYNOPSIS

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

FN_ref_t *fn_ref_create(const FN_identifier_t *ref_type);
void fn_ref_destroy(FN_ref_t *ref);
FN_ref_t *fn_ref_copy(const FN_ref_t *ref);
FN_ref_t *fn_ref_assign(FN_ref_t *dst, const FN_ref_t *src);
const FN_identifier_t *fn_ref_type(const FN_ref_t *ref);
unsigned int fn_ref_addrcount(const FN_ref_t *ref);
const FN_ref_addr_t *fn_ref_first(const FN_ref_t *ref, void **iter_pos);
const FN_ref_addr_t *fn_ref_next(const FN_ref_t *ref, void **iter_pos);
int fn_ref_prepend_addr(FN_ref_t *ref, const FN_ref_addr_t *addr);
int fn_ref_append_addr(FN_ref_t *ref, const FN_ref_addr_t *addr);
int fn_ref_insert_addr(FN_ref_t *ref, void **iter_pos, const FN_ref_addr_t *addr);
int fn_ref_delete_addr(FN_ref_t *ref, void **iter_pos);
int fn_ref_delete_all(FN_ref_t *ref);
FN_ref_t *fn_ref_create_link(const FN_composite_name_t *link_name);
int fn_ref_is_link(const FN_ref_t *ref);
FN_composite_name_t *fn_ref_link_name(const FN_ref_t *link_ref);
FN_string_t *fn_ref_description(const FN_ref_t *ref, unsigned int detail, unsigned int *more_detail);

DESCRIPTION

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.

RETURN VALUES

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()

USAGE

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

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe

SEE ALSO

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)

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

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | USAGE | ATTRIBUTES | SEE ALSO | NOTES