Tribblix: manual page: str_to

STR_TO_LABEL(3TSOL) Trusted Extensions Library Functions

NAME

str_to_label - parse human readable strings to label

SYNOPSIS

cc [flag...] file... -ltsol [library...]

#include <tsol/label.h>

int str_to_label(const char *string, m_label_t **label,
const m_label_type_t label_type, uint_t flags, int *error);

DESCRIPTION

The str_to_label() function is a simple function to parse human
readable strings into labels of the requested type.

The string argument is the string to parse. If string is the result
of a label_to_str() conversion of type M_INTERNAL, flags are ignored,
and any previously parsed label is replaced.

If *label is NULL, str_to_label() allocates resources for label and
initializes the label to the label_type that was requested before
parsing string.

If *label is not NULL, the label is a pointer to a mandatory label
that is the result of a previously parsed label and label_type is
ignored. The type that is used for parsing is derived from label for
any type-sensitive operations.

If flags is L_MODIFY_EXISTING, the parsed string can be used to
modify this label.

If flags is L_NO_CORRECTION, the previously parsed label is replaced
and the parsing algorithm does not attempt to infer missing elements
from string to compose a valid label.

If flags is L_DEFAULT, the previously parsed label is replaced and
the parsing algorithm makes a best effort to imply a valid label from
the elements of string.

If flags contains L_CHECK_AR logically OR-ed with another value, the
resulting label will be checked to ensure that it is within the
"Accreditation Range" of the DIA encodings schema. This flag is
interpreted only for MAC_LABEL label types.

The caller is responsible for freeing the allocated resources by
calling the m_label_free() function. label_type defines the type for
a newly allocated label. The label type can be:

MAC_LABEL
The string should be translated as a Mandatory Access
Control (MAC) label.

USER_CLEAR
The string should be translated as a label that
represents the least upper bound of the labels that the
user is allowed to access.

If error is NULL, do not return additional error information for
EINVAL. The calling process must have mandatory read access to label
and human readable string. Or the calling process must have the
sys_trans_label privilege.

The manifest constants ADMIN_HIGH and ADMIN_LOW are the human
readable strings that correspond to the Trusted Extensions policy
admin_high and admin_low label values. See labels(7).

RETURN VALUES

Upon successful completion, the str_to_label() function returns 0.
Otherwise, -1 is returned, errno is set to indicate the error, and
error provides additional information for EINVAL. Otherwise, error is
a zero-based index to the string parse failure point.

ERRORS

The str_to_label() function will fail if:

EINVAL
Invalid parameter. M_BAD_STRING indicates that string
could not be parsed. M_BAD_LABEL indicates that the label
passed in was in error. M_OUTSIDE_AR indicates that the
resulting label is not within the "Accreditation Range"
specified in the DIA encodings schema.

ENOTSUP
The system does not support label translations.

ENOMEM
The physical limits of the system are exceeded by size
bytes of memory which cannot be allocated.

ATTRIBUTES

WARNINGS

A number of the parsing rules rely on the DIA label encodings schema.
The rules might not be valid for other label schemata.

NOTES

The functionality described on this manual page is available only if
the system is configured with Trusted Extensions.

June 15, 2009 STR_TO_LABEL(3TSOL)