This operation creates a handle to an FN_ctx_t object using an FN_ref_t object for that context.

authoritative specifies whether the handle to the context returned should be authoritative with respect to information the context obtains from the naming service. When the flag is non-zero, subsequent operations on the context will access the most authoritative information. When authoritative is 0, the handle to the context returned need not be authoritative.

This operation returns a pointer to an FN_ctx_t object if the operation succeeds; otherwise, it returns a NULL pointer (0).

fn_ctx_handle_from_ref() sets status as described in FN_status_t(3XFN) and xfn_status_codes(3XFN). The following status code is of particular relevance to this operation:

FN_E_NO_SUPPORTED_ADDRESS

A context object could not be constructed from a particular reference. The reference contained no address type over which the context interface was supported.

Authoritativeness is determined by specific naming services. For example, in a naming service that supports replication using a master/slave model, the source of authoritative information would come from the master server. In some naming systems, bypassing the naming service cache may reach servers which provide the most authoritative information. The availability of an authoritative context might be lower due to the lower number of servers offering this service. For the same reason, it might also provide poorer performance than contexts that need not be authoritative.

Applications set authoritative to 0 for typical day-to-day operations. Applications only set authoritative to a non-zero value when they require access to the most authoritative information, possibly at the expense of lower availability and/or poorer performance.

To control the authoritativeness of the target context, the application first resolves explicitly to the target context using fn_ctx_lookup(3XFN). It then uses fn_ctx_handle_from_ref() with the appropriate authoritative argument to obtain a handle to the context. This returns a handle to a context with the specified authoritativeness. The application then uses the XFN operations, such as lookup and list, with this context handle.

It is implementation-dependent whether authoritativeness is transferred from one context to the next as composite name resolution proceeds. The application should use the approach recommended above to achieve the desired level of authoritativeness on a per context basis.

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

FN_ctx_t(3XFN), FN_ref_t(3XFN), FN_status_t(3XFN), fn_ctx_get_ref(3XFN), fn_ctx_handle_destroy(3XFN), fn_ctx_lookup(3XFN), xfn(3XFN), xfn_status_codes(3XFN), attributes(5), fns_references(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.