escap_parse_fields(3)escap_parse_fields(3)NAME
escap_parse_fields, escap_print_fields, escap_cmp_fields,
escap_copy_fields, escap_size_data - parser routines for authcap-style
data (Enhanced Security)
SYNOPSIS
#include <prot.h>
int escap_parse_fields
struct escap_parse const *partab,
size_t fieldlen,
void *fieldptr,
uint_t *flagptr,
char *buffer,
struct escap_pad *unkpad,
struct escap_pad *scrpad ); int escap_print_fields
struct escap_parse const *partab,
size_t fieldlen,
void const *fieldptr,
uint_t const *flagptr,
FILE *fp ); int escap_cmp_fields
struct escap_parse const *partab,
size_t fieldlen,
void const *fieldptr,
void const *fieldptr2,
uint_t const *flagptr,
uint_t const *flagptr2,
uint_t **diffptr ); int escap_copy_fields
struct escap_parse const *partab,
size_t fieldlen,
void *dstfieldptr,
void const *srcfieldptr,
uint_t *dstflagptr,
uint_t const *srcflagptr,
struct escap_pad *scrpad ); size_t escap_size_data
struct escap_parse const *partab,
size_t fieldlen,
void const *fieldptr,
uint_t const *flagptr );
LIBRARY
Security Library (libsecurity.so)
PARAMETERS
Pointer to a list of escap_parse structures, terminated by an entry
with a NULL fname field. The size of the data area referenced by the
fieldptr, fieldptr2, srcfieldptr, dstfieldptr parameters. Pointer to
storage for the fixed-length data. For example, when parsing an
extended profile, this should be a pointer to an espw_field structure.
Additional pointer (like fieldptr) for comparisons. Source for data
copying, otherwise like fieldptr. Read-only. Destination for data
copying, otherwise like fieldptr. Pointer to the storage area for
flags associated with fieldptr. For example, when parsing an extended
profile, this should be a pointer to an espw_flag structure. Addi‐
tional pointer (like flagptr) for comparisons. Source for data copy‐
ing, otherwise like flagptr. Read-only. Destination for data copying,
otherwise like flagptr. Pointer to a pointer to flag data, or pointer
to a NULL pointer to have escap_cmp_fields allocate storage, or NULL to
indicate that the mask of which fields are different is not desired by
the caller. Pointer to an escap_pad structure that is used for storing
variable-sized data elements which are referenced by fieldptr (or dst‐
fieldptr). If its area field is NULL, storage is allocated. Pointer to
an escap_pad structure used for holding a record of unparsable fields.
If its area field is NULL, storage will be allocated. pointer to a
text record to be parsed. The text record is expected to meet the for‐
matting requirements for an authcap record. Standard I/O control
pointer for output of a text record representing the fields and flags
described by partab, fieldptr, and flagptr.
DESCRIPTION
The escap_parse_fields() routine parses the text in buffer according to
the field information in partab, storing the results in the data area
referenced by fieldptr and the flags for which fields are parsed in the
area referenced by flagptr. This routine never writes to an offset in
the field data area greater than fieldlen. Initialization of the field
and flag data areas to zeros is the responsibility of the calling rou‐
tine, and not of escap_parse_fields(). If the data areas of the scrpad
and unkpad parameters are NULL on entry to this function, the scrpad
area will be allocated an area of size equal to strlen(buffer)*2+2 and
the unkpad area will receive an allocation of strlen(buffer)+1. If the
first element of the partab parameter has an fname field of zero
length, then it is assumed that the first field is an unnamed copy of
the name of the entry (the portion preceding the first un-quoted \
character). The :chkent: field which is expected at the end of any
authcap buffer is not expected to be an element of partab, since there
is usually no flag field associated with it.
Structures for Reference
struct escap_parse { const char *fname; /* name of the field in
the buffer */ int ptype; /* parser type (from above list)
*/ uint_t fmax; /* field maximum, special in many
cases */ size_t where; /* how far into the field to
store */ size_t nmlen; /* strlen of fname field */ };
struct escap_pad { char *area; /* where the region begins
*/ char *next; /* where next string will go */ char
*aend; /* last legal place to write */ size_t
size; /* how big the last allocation was */ };
extern struct escap_parse const espw_parse[], esdv_parse[],
estc_parse[], esfi_parse[], esdf_parse[];
escap_parse_fields() checks each field-name found for a matching entry
in partab, adding the field to the data stored in unkpad if it can find
no match for the name, or if the fieldlen parameter will not allow the
data to be saved in the fields area, or if the routine it calls to
parse the data fails. The length restrictions in the fmax field of the
partab entry may be the cause of the parse failure. The flags data
storage is updated in the order in which the fields are listed in the
partab parameter.
This routine returns -1 if memory allocation fails or if storing the
variable-length data in scrpad or unkpad fails because the allocation
was not sufficient. It returns 0 if all fields were parsed and stored
successfully (ignoring fields that have required a storage offset
exceeding fieldlen). It returns a count of the failed fields which
were appended to the unkpad storage because of parse failure otherwise.
The escap_print_fields() routine uses the fp argument to display the
fields described by partab, fieldptr, and flagptr. It will reference
no offset in the field storage area beyond fieldlen. For each field
described by partab, if its storage is within the limit imposed by
fieldlen, if the corresponding bit is set in the flags area, then an
entry for that field is written to fp. It returns 0 on error (fprintf
failure) or 1 on success.
The escap_cmp_fields() routine uses the partab and fieldlen arguments
to compare the data areas referenced by the fieldptr and fieldptr2
pointers and the flag areas referenced by the flagptr and flagptr2
pointers. If diffptr is NULL, the return value is 0 if the flags masks
are equal and the data elements which they represent as being present
are equivalent. If diffptr is not NULL, then a flags mask indicating
which fields differed will be returned in *diffptr. If *diffptr is
NULL on entry, this routine will allocate storage for this flag area.
If that allocation fails, the routine returns -1. A difference will be
recorded if the flag bit for a given field in *flagptr is not the same
as the corresponding bit in *flagptr2, or if both flag areas indicate
that the field is present, but that a comparison of the data referenced
by fieldptr and fieldptr2 shows a difference. If *diffptr was non-NULL
or successfully allocated, the return value of this routine is the same
as when diffptr is NULL (0 for equal entries, 1 for unequal).
The escap_copy_fields() routine copies data and flag information from
srcfieldptr and srcflagptr to dstfieldptr and dstflagptr, limiting the
data offset referenced in the field storage areas to fieldlen as
directed by the partab parameter. Variable-sized data is appended to
scrpad. If the area and size fields of scrpad are NULL, this routine
assigns storage to scrpad based on a call to escap_size_data(). Ini‐
tialization of the destination flag values to zero is the responsibil‐
ity of the calling routine. This routine will only set bits in the des‐
tination flags area, not clear them. This routine does perform a mem‐
cpy(dstfieldptr, srcfieldptr, fieldlen). This routine returns 0 if it
could not append to the scrpad area or if allocation of the scrpad area
failed. It returns 1 otherwise.
The escap_size_data() routine evaluates the additional size needed
beyond fieldlen bytes to store the variable-sized data associated with
the fieldptr parameter as described by partab and flagptr . It returns
only the size needed to store variable-sized data, and does not include
fieldlen in that calculation, so it can return 0.
NOTES
In order to quickstart a program, the program must be linked as fol‐
lows:
-lsecurity -ldb -laud -lm
See the shared library discussion in the Programmer's Guide for more
information about using the quickstarting feature.
RETURN VALUES
See above.
EXAMPLE
The following is an example of an actual call: struct es_passwd *sta‐
tus; struct es_pad uunk, upad; char *abuf; /* ... */ uunk.area =
upad.area = NULL; if (escap_parse_fields(espw_parse, status->fieldlen,
status->ufld, (uint_t*) status->uflg,
abuf, &uunk, &upad) == -1)
status = 0; else /* ... */
SEE ALSO
Functions: getespwent(3), getesdvent(3), getestcent(3), getesfient(3),
getesdfent(3)
Files: authcap(4)
Security
escap_parse_fields(3)