Introduction to Library Functions puid_char(3)
NAME
puid_ck4macro(), puid_expandmacro(), puid_getcharall(),
puid_getcharbyaddr(), puid_getcharbyname(), puid_getenv(),
puid_hashXch(), puid_loadchars(), puid_loadmacros() - pro-
cess authorization characteristic information
SYNOPSIS
#include <puid_char.h>
int puid_ck4macro( char * x, size_t xl )
int puid_expandmacro( char * v, size_t vl, char ** xr ,
size_t * xrl, int * xd, char **em )
int puid_getcharall( puid_char_t ***pc, int sort, char * cfp
, char ** le, size_t *lel )
char *puid_getcharbyaddr( int number, char * cfp , char **
le, size_t * lel )
int puid_getcharbyname( char * name, char * cfp , char **
le, size_t * lel )
char *puid_getenv( char * nm, char * dv )
int puid_hashXch( char * c, int case, size_t cl )
int puid_loadchars( char * cfp, char ** le, size_t * lel )
int puid_loadmacros( char * mfp, char ** le, size_t * lel )
DESCRIPTION
Functions of the characteristic processing family obtain
information about authorization characteristics and macros
of the Purdue Infrastructure for Identification, Authentica-
tion, and Authorization (I2A2) system. Authorization
characteristics are indicators of relationships associated
with PUIDs (Purdue University IDentification numbers).
Authorization macros are combinations of authorization
characteristic tests.
The two functions puid_loadchars() and puid_loadmacros() may
be used before calling any lookup functions, but that isn't
necessary, since the lookup functions will call them if they
haven't already been called.
int puid_ck4macro( char * x, size_t xl )
returns an indication of the absence or presence of a
macro or characteristic name in a Boolean characteris-
tic expression. Absence is indicated by a zero return;
presence, by a one.
SunOS 5.8 Last change: 1
Introduction to Library Functions puid_char(3)
A pointer to the Boolean characteristic expression is
supplied in the x argument; its length in the xl argu-
ment.
int puid_expandmacro( char * v, size_t vl, char ** xr ,
size_t * xrl, int * xd, char **em )
expands the Boolean characteristic expression, contain-
ing a macro or characteristic name, pointed to by the v
argument. The vl argument gives the length of the
expression.
The expanded value is returned in a character string
whose pointer address must be supplied in the xr argu-
ment. The length of the expanded value is returned in
the address given by the xrl argument. The caller must
set xr to NULL and xrl to zero before calling
puid_expandmacro().
The xd argument supplies a pointer to a counter that
controls macro expansion depth. The caller must set it
to zero before calling puid_expandmacro(). The maximum
macro expansion depth is defined by PUID_MACRO_DEPTH in
puid_char.h.
The em argument supplies a destination for macro expan-
sion error messages. The caller must set it to NULL
before calling puid_expandmacro().
Puid_expandmacro(). returns a zero value if the expan-
sion went without incident. It returns a non-zero
positive value if some error was detected; the returned
value will be a PUID_E* value, as defined in
puid_errno.h, and may be accompanied by an error mes-
sage whose pointer will be returned in the *em argu-
ment.
int puid_getcharall( puid_char_t ***pc, int sort, char * cfp
, char ** le, size_t *lel )
returns a count of the number of characteristics avail-
able in the table of pointers whose address is returned
via pc. If the return value is less than one, no
characteristics are available, and error messages
returned via the le and lel arguments may indicate the
cause of the load failure. See the LOAD ERRORS section
for more information on using those receptors.
The pointers of pc address a sorted table whose entries
have this structure:
typedef struct puid_char {
SunOS 5.8 Last change: 2
Introduction to Library Functions puid_char(3)
int pc_nbr; /* characteristic number */
char *pc_nm; /* characteristic name */
} puid_char_t;
The sort argument specifies whether the returned table
will be sorted by characteristic number (sort ==
PUID_CHAR_BYNBR) or name (sort == PUID_CHAR_BYNM). The
PUID_CHAR_BY* symbols are defined in puid_char.h.
The optional cfp argument may supply a path to a file
containing authorization characteristics. If no path
is supplied, the default PUID_CHAR_FILE will be used.
(See FILES.)
The optional le and lel arguments may be supplied to
receive messages about errors detected during the load-
ing of characteristics. See the LOAD ERRORS section
for more information on using those receptors.
For an example of how to use puid_getcharall(), see the
EXAMPLES section.
char *puid_getcharbyaddr( int number, char * cfp , char **
le, size_t * lel )
returns a character pointer to a name for a charac-
teristic whose number is supplied in the number argu-
ment - e.g, a characteristic number of 1234 may return
the string "genealogist". (That's an imaginary charac-
teristic number and name.)
Name comparisons ignore case.
The optional cfp argument may supply a path to a file
containing authorization characteristics. If no path
is supplied, the default PUID_CHAR_FILE will be used.
(See FILES.)
If no characteristic number can be found or if charac-
teristic load errors occurred, a NULL pointer will be
returned, and the optional le and lel arguments may
contain information about errors. See the LOAD ERRORS
section for more information on using those receptors.
int puid_getcharbyname( char * name, char * cfp , char **
le, size_t * lel )
returns the characteristic number for the name of a
characteristic supplied in the name argument - e.g.,
supplying "genealogist" might return 1234. (That's an
imaginary characteristic number and name.)
SunOS 5.8 Last change: 3
Introduction to Library Functions puid_char(3)
Defined symbols for some characteristic names may be
found in puid_char.h.
The optional cfp argument may supply a path to a file
containing authorization characteristics. If no path
is supplied, the default PUID_CHAR_FILE will be used.
(See FILES.)
If no characteristic number can be found or if charac-
teristic load errors occurred, a NULL pointer will be
returned, and the optional le and lel arguments may
contain information about errors. See the LOAD ERRORS
section for more information on using those receptors.
char *puid_getenv( char * nm, char * dv )
returns an environment value or a default value for a
parameter value. Usually the environment variable
name, supplied in the nm argument, and the default
value name, supplied in the dv argument, are the same -
e.g., PUID_CHAR_FILE, PUID_MACRO_FILE, etc.
int puid_hashXch( char * c, int case, size_t cl )
returns a hash index, modulo the m argument, based upon
the cl characters in the string pointed to by the c
argument. Case is ignored if the value of the case
argument is PUID_CASE_IGNORE; significant, if
PUID_CASE_USE. The PUID_CASE_* symbols may be found in
puid_char.h.
int puid_loadchars( char * cfp, char ** le, size_t * lel )
loads characteristics from a file at the optional path
defined by the cfp argument. If no path is supplied,
the default PUID_CHAR_FILE will be used. (See FILES.)
If the return value is less than zero, it indicates an
error. Error values are represented by PUID_ECHAR_*
symbols from puid_char.h. If the return value is zero,
no error was detected. The ChTabSt global variable,
defined in puid_char.h, contains a count of the number
of characteristics that were loaded.
The optional le and lel arguments may be supplied to
receive messages about errors detected during the load-
ing of characteristics. See the LOAD ERRORS section
for more information on using those receptors.
int puid_loadmacros( char * mfp, char ** le, size_t * lel )
loads characteristic macros from a file at the optional
SunOS 5.8 Last change: 4
Introduction to Library Functions puid_char(3)
path defined by the mfp argument. If no path is sup-
plied, the default PUID_MACRO_FILE will be used. (See
FILES.)
If the return value is less than zero, it indicates an
error. Error values are represented by PUID_EMACRO_*
symbols from puid_char.h. If the return value is zero,
no error was detected. The MacTabSt global variable,
defined in puid_char.h, contains a count of the number
of macros that were loaded.
The optional le and lel arguments may be supplied to
receive messages about errors detected during the load-
ing of characteristic macros. See the LOAD ERRORS sec-
tion for more information on using those receptors.
RETURN VALUES
See the individual function descriptions in the DESCRIPTION
section for information on return values. See the LOAD
ERRORS for information on processing returned error mes-
sages.
LOAD ERRORS
Many characteristic processing functions will return error
messages via the le argument.
The le argument will be a pointer to a set of error mes-
sages, separated by NUL characters. The lel argument
returns the total number of characters in all error mes-
sages.
Before calling any function that might set le (via *le) or
lel the caller must set le to NULL and lel to zero.
To process the messages returned via le and lel, a C program
must begin at le and treat it as a NUL terminated string.
It must then find the next message by skipping past the next
NUL character, limited by the total number of characters
returned. The processing code might look like this:
#include "puid_char.h"
#include <string.h>
char *le = (char *)NULL;
size_t lel = (size_t)0;
if (puid_loadchars(NULL, &le, &lel) && le) {
char *m, *ms;
size_t len;
for (m = le, len = lel; m && *m && (len < lel); m++) {
(void) printf("Load error: %s\n", m);
SunOS 5.8 Last change: 5
Introduction to Library Functions puid_char(3)
ms = m;
if ((m = strchr(m, '\0')) = (char *)NULL)
break;
len += (size_t)(m - ms + 1);
}
}
EXAMPLES
See authzchar(1) for a simple application that uses the
functions of the characteristic processing family.
The following example looks up the name for characteristic
1234 in the file ./chars, tests the result, and prints an
interpretation of the result.
#include "puid_char.h"
char *le, *nm;
size_t lel;
nm = puid_getcharbyaddr(1234, "./chars", &le, &lel);
if (nm == (char *)NULL) {
if (le != (char *)NULL) {
/* Process load errors. */
}
nm = "(unknown)";
}
(void) printf("1234's name is %s\n", nm);
The following example uses puid_getcharall() to list all
characteristic numbers and names in the default characteris-
tics file in characteristic name order.
#include "puid_char.h"
int i, n;
char *le;
size_t lel;
puid_char_t **p;
if ((n = puid_getcharall(&p, PUID_CHAR_BYNM), NULL,
&le, &lel) > 0)
{
for (i = 0; i < n; i++) {
(void) printf("%d: %s\n", p[i]->pc_nbr,
p[i]->pc_nm ? p[i]->pc_nm
: "(unknown)");
}
} else {
(void) printf("No characteristics\n");
if (le) {
/* Process load errors. */
SunOS 5.8 Last change: 6
Introduction to Library Functions puid_char(3)
}
}
FILES
/var/local/puid/authz/chars
is the default path to the characteristics file. This
path is defined by PUID_CHAR_FILE in puid_char.h. The
PUID_CHAR_FILE environment variable and the cfp argument
to the characteristics functions will over-ride the
default.
This file contains data to map characteristic numbers to
names. Its format is defined in comments at the begin-
ning of the standard version of the file, used by the
I2A2 system. The standard file can be downloaded from:
http://www.i2a2.purdue.edu/characteristics/char.txt
/var/local/puid/authz/macros
is the default path to the characteristics macro defini-
tions file. This path is defined by PUID_MACRO_FILE in
puid_char.h. The PUID_MACRO_FILE environment variable
and the mfp argument to the characteristic macro func-
tions will over-ride the default.
This file maps macro names to Boolean characteristic
authorization expressions. Its format is defined in
comments at the beginning of the standard version of the
file, used by the I2A2 system. The standard file can be
downloaded from:
http://www.i2a2.purdue.edu/characteristics/macros.txt
AUTHOR
The characteristic lookup function family was written by
Victor A. Abell <abe@purdue.edu>.
SEE ALSO
authzchar(1).
SunOS 5.8 Last change: 7
Feedback |
Contact Purdue
Maintained by: IAMO Team
Purdue University, West Lafayette, IN 47907, (765) 494-4600
© 2010 - 2013 Purdue University |
An equal access/equal opportunity university |
Copyright Complaints
If you have trouble accessing this page because of a disability, please contact the CSC at itap@purdue.edu or (765) 494-4000.