 |
Index for
Section 3 |
|
 |
Alphabetical
listing for E |
|
 |
Bottom of
page |
|
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
partab
Pointer to a list of escap_parse structures, terminated by an entry
with a NULL fname field.
fieldlen
The size of the data area referenced by the fieldptr, fieldptr2,
srcfieldptr, dstfieldptr parameters.
fieldptr
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.
fieldptr2
Additional pointer (like fieldptr) for comparisons.
srcfieldptr
Source for data copying, otherwise like fieldptr. Read-only.
dstfieldptr
Destination for data copying, otherwise like fieldptr.
flagptr
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.
flagptr2
Additional pointer (like flagptr) for comparisons.
srcflagptr
Source for data copying, otherwise like flagptr. Read-only.
dstflagptr
Destination for data copying, otherwise like flagptr.
diffptr
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.
scrpad
Pointer to an escap_pad structure that is used for storing variable-
sized data elements which are referenced by fieldptr (or dstfieldptr).
If its area field is NULL, storage is allocated.
unkpad
Pointer to an escap_pad structure used for holding a record of
unparsable fields. If its area field is NULL, storage will be
allocated.
buffer
pointer to a text record to be parsed. The text record is expected to
meet the formatting requirements for an authcap record.
fp 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 routine, 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(). Initialization of the destination
flag values to zero is the responsibility of the calling routine. This
routine will only set bits in the destination flags area, not clear them.
This routine does perform a memcpy(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 follows:
-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 *status;
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for E |
|
 |
Top of
page |
|