str_to_label(3TSOL)				       Trusted Extensions Library Functions				       str_to_label(3TSOL)

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 pars-
       ing 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.

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

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.

       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

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+
       |Standard		     |See below.		   |
       +-----------------------------+-----------------------------+

       Parsing types that are relative to Defense Intelligence Agency (DIA) encodings schema are Standard. Standard is specified  in  label_encod-
       ings(4).

SEE ALSO

       label_to_str(3TSOL), libtsol(3LIB), m_label(3TSOL), label_encodings(4), attributes(5), labels(5)

       Validating the Label Request Against the Printer's Label Range in Solaris Trusted Extensions Developer's Guide

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.

SunOS 5.11							    20 Jul 2007 					       str_to_label(3TSOL)