| |
| XFN Interface Library Functions | fn_ctx_equivalent_name(3XFN) |
| | fn_ctx_equivalent_name - construct an equivalent name in same context |
SYNOPSIS
| |
#include <xfn/xfn.h>
FN_composite_name_t *fn_ctx_equivalent_name(FN_ctx_t *ctx, const FN_composite_name_t *name, const FN_string_t *leading_name, FN_status_t * status); |
| |
Given the name of an object name relative to the context ctx, this operation returns an equivalent name for that object, relative to the same
context ctx, that has leading_name as its initial atomic name. Two names are said to be equivalent if they have prefixes that resolve to the same context,
and the parts of the names immediately following the prefixes are identical.
The existence of a binding for leading_name in ctx does not guarantee that a name equivalent to name can be constructed.
The failure may be because such equivalence is not meaningful, or due to the inability of the system to construct a name with the equivalence. For example, supplying _thishost as leading_name when name starts with _myself to fn_ctx_equivalent_name() in the Initial Context would not be meaningful; this
results in the return of the error code FN_E_NO_EQUIVALENT_NAME.
|
| |
If an equivalent name cannot be constructed, the value 0 is returned and status is set appropriately.
|
| |
fn_ctx_equivalent_name() sets status as described in FN_status_t(3XFN) and xfn_status_codes(3XFN). The following status
code is especially relevant for this operation:
-
FN_E_NO_EQUIVALENT_NAME
- No equivalent name can be constructed, either
because there is no meaningful equivalence between name and leading_name, or the system does not support constructing the requested equivalent name,
for implementation-specific reasons.
|
| | Example 1. Naming Files
| |
In the Initial Context supporting XFN enterprise policies, a user jsmith is able to name one of her files relative to this context in several ways.
| |
_myself/_fs/map.ps
_user/jsmith/_fs/map.ps
_orgunit/finance/_user/jsmith/_fs/map.ps
|
The first of these may be appealing to the user jsmith in her day-to-day operations. This name is not, however, appropriate for her to use when referring the file in an electronic
mail message sent to a colleague. The second of these names would be appropriate if the colleague were in the same organizational unit, and the third appropriate for anyone in the same enterprise.
When the following sequence of instructions is executed by the user jsmith in the organizational unit finance, enterprise_wide_name would contain
the composite name _orgunit/finance/_user/jsmith/_fs/map.ps:
| |
FN_string_t* namestr =
fn_string_from_str((const unsigned char*)"_myself/_fs/map.ps");
FN_composite_name_t* name = fn_composite_name_from_string(namestr);
FN_string_t* org_lead =
fn_string_from_str((const unsigned char*)"_orgunit");
FN_status_t* status = fn_status_create();
FN_composite_name_t* enterprise_wide_name;
FN_ctx_t* init_ctx = fn_ctx_handle_from_initial(status);
/* check status of from_initial() */
enterprise_wide_name = fn_ctx_equivalent_name(init_ctx, name, org_lead,
status);
|
When the following sequence of instructions is executed by the user jsmith in the organizational unit finance, shortest_name would contain
the composite name _myself/_fs/map.ps:
| |
FN_string_t* namestr =
fn_string_from_str((const unsigned char*)
"_orgunit/finance/_user_jsmith/_fs/map.ps");
FN_composite_name_t* name = fn_composite_name_from_string(namestr);
FN_string_t* mylead = fn_string_from_str((const unsigned char*)"_myself");
FN_status_t* status = fn_status_create();
FN_composite_name_t* shortest_name;
FN_ctx_t* init_ctx = fn_ctx_handle_from_initial(status);
/* check status of from_initial() */
shortest_name = fn_ctx_equivalent_name(init_ctx, name, mylead, status);
|
|
|
| |
See attributes (5) for descriptions of the following
attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| MT-Level | MT-Safe |
|
| |
