man libcci
NAME
abend, cc_abend, efopen, efopen_umask, efwrite, efread, efseek, ua_arg_get,
ua_arg_show, ua_chk_list, ua_dlm_list, ua_delim, wldcmp, etoa, ptod, ptoc,
ua_get_ps, crypt_passwd, find_uid yy_ddd, yy_mmdd, libcci - cci subroutine
library
LIBRARY
libcci.a cci subroutine library.
The routines are broken into the following sections:
ROUTINES EXIT (program exit routines)
abend, cc_abend
ROUTINES FILE (enhanced file routines)
efopen, efopen_umask, efwrite, efread, efseek
ROUTINES ARGS (argument and string parsing routines)
ua_arg_get, ua_arg_show,
ua_chk_list, ua_dlm_list,
ua_delim, wldcmp
ROUTINES CONV (data conversion routines)
etoa, ptoc, ptod,
ua_get_ps, crypt_passwd, find_uid
yy_ddd, yy_mmdd
DESCRIPTION
The libcci subroutine started as a collection of C subroutines to use under
IBM/MVS with development under VAX/VMS and subsequently were wrapped into a
number of utilities which were converted later to UNIX. A number of pro-
grams utilize these routines, including those included in the uak, uak-
pacct, and uaio packages under ftp://ftp.alaska.edu/pub/sois/
Reference the comments in routine source and the supplied programs as exam-
ples and for additional information.
Use: #include uaccilib.h and compile with 'cc <program>.c libcci.a'.
ROUTINES EXIT (program exit)
void abend (char *format, void *arg1, void *arg2, void *arg3)
Abort program after issuing message. Message is in printf format with
a maximum of 3 arguments.
Return: (void)
void cc_abend (int exit, char *format, void *arg1, void *arg2, void *arg3)
Exit (if exit is non-zero) or abort program after issuing message.
Return: (void)
ROUTINES FILE (enhanced file)
FILE *efopen (char *file, char *mode, int exit)
Issue getenv() then fopen() checking status.
Arguments are like fopen() with exit added for program exit code, if
exit is 0 efopen() returns.
Return: like fopen()
FILE *efopen_umask (char *file, char *mode, int exit, mode_t mask)
Issue umask() then efopen() then resets umask().
Return: like fopen()
int efwrite (char *ptr, int siz, int num, FILE *fpt, int exit)
Issue fwrite() checking status.
Arguments are like fwrite() with exit addded.
Return: like fwrite()
int efread (char *ptr, int siz, int num, FILE *fpt, int exit)
Issue fread() checking status.
Arguments are like fread() with exit addded.
Return: like fread()
int efseek (FILE *fpt, long offset, long from, int exit)
Issue fseek() checking status.
Arguments are like fseek() with exit addded.
Return: like fseek()
int efprintf (FILE *ot, char *line, int exit, char *file)
Issue fprintf() checking status.
This is a limited fprintf with an implied format of "%s". The exit
argument behaves like the other ef*() routines and file is an optional
argument with the actual filename.
Return: like fprintf()
ROUTINES ARGS (argument and string parsing)
int ua_arg_get (int argc, char *argv[], struct UA_ARG *ua_a, int exit)
Parse standard arguments.
See one of the supplied programs for examples.
Argument types can be (from uaccilib.h):
UA_Arg_C comments
UA_Arg_A argument (parameter)
UA_Arg_Z argument (parameter), variable amount
UA_Arg_F flag
UA_Arg_I integer
UA_Arg_S string
UA_Arg_X action
UA_Arg_V action value
UA_Arg_O integer octal
UA_Arg_H integer hexadecimal
This is the primary routine of cci command parser utilized by non-UNIX
operating systems instead of the traditional UNIX getopt() parsing.
Options can be been defined to "look like" UNIX style options, but can
be spelled out or generally abbreviated. For example '-o' is the same
as '-output'. Because of this multiple options must be space
separated and the hyphen is part of the option name. Also because of
this order of options and arguments is irrelevant.
Return: 0 or action
int ua_arg_show (struct UA_Arg *ua_a)
Show parsed arguments.
Return: (void)
int ua_dlm_list (char *str, char *dlm, char *display)
Parse string by delimeters defined (or default).
Default delimiters are comma, space, tab or newline. The string is
reconstructed removing removing consecutive delimiters and replacing
them with a NULL. The resulting string is a series of strings with
the return indicating how many strings.
The display argument is essentially for debugging, if non-null the
fields will be displayed.
Return: count of delimited fields found.
int ua_chk_list (char *list, int count, char *base, int max, int flag)
Check whether base string in list.
Arguments:
list series of strings, such as ua_dlm_list()
count count of strings in list
base base string to check for
max maximum length of base string
flag flags for wldcmp() comaprison
The base string is compared against the series of strings which may
contain wildcard characters, see wldcmp().
Return: 1 if match found else 0 if no match.
int ua_delim (char *line, char delim, char *fields[], int max)
Establish field pointers.
Arguments:
line is a string
delim is a char (field delimiter)
fields is an arry of strings, pointers are returned
max is the size of the fields array
Note, delimiters will be NULL'd as will white space before the delim-
iter. Null fields can be defined by adjacent delimiters.
Return: count of delimited fields found (fields[] is built).
char *wldcmp (char *str, char *strw, int options)
Compare string with wildcarded string. Comparison stops when strw is
exhausted or upon failure.
Use: #include wldcmp.h
Arguments:
str string to check
strw string with wildcards to check against
options
first byte is single character match
(00 use '%', ff then none)
second byte is multiple character match
(00 use '*', ff then none)
third and fourth bytes represent the mask
defined below.
mask &
0x01 WLD_UPR indicates ignore case
0x02 WLD_WHT indicates ignore extended white space
(white space defined as: *char <= ' ').
Length of white space will be checked
to the extent strw remains white.
0x04 WLD_FND indicates implied wildcard at front
0x08 WLD_TRA indicates there do not need to be any
characters for trailing wildcard.
0x10 WLD_NOT indicates no implied wildcard at end
Options may be passed as an int (32) value with integral mask if
default wild characters are acceptable. Likewise, passing an integer
0 will select no options.
Wildcards:
'*' or as defined by 2nd options byte, match anything
'%' or as defined by 1st options byte, match exactly one character
Return:
0 if comparison failures
char* address of next character within str;
note, if strw ends with '*' then address of first
matching character will be returned.
Examples:
result str strw mask
------ --- ---- ----
ok "ABC" "ABC" 0
^
ok "ABCDEF" "A%C" 0
^
ok "ABCDEF" "A*D" 0
^
bad "ABC" "abc" 0
ok "ABCD" "abc" 1 (WLD_UPR
^
bad "A BCDE" "a b" 1 (WLD_UPR)
bad "A BCDE" "a b" 2 (WLD_WHT)
ok "A BCDE" "a b" 3 (WLD_UPR | WLD_WHT)
^
bad "A B" "a b" 3 (WLD_UPR | WLD_WHT)
ok "A B" "a b" 3 (WLD_UPR | WLD_WHT)
^
ok "ABCABCDE" "*ABCD" 0
^
ok "ABCABCDE" "ABCA" 4
bad "ABCABCDE" "ABCA" 0 (WLD_NOT)
bad "ABCABCDE" "ABCD" 0
ok "ABCABCDE" "ABCD" 4 (WLD_FND)
^
bad "ABCD" "*D*" 0
ok "ABCD" "*D*" 8 (WLD_TRA)
^
See also wldcmp_v.c validation program for examples above (and more).
ROUTINES CONV (data conversion)
int etoa (char *str, int length)
EBCDIC to ASCII string conversion.
Use: #include etoa.h
Return: (void)
int ptoc (char *str, int offset, int length, char *result)
Packed decimal to character conversion. The offset is in half bytes
to the first half byte and the length of the input string is specified
in half bytes.
Return: 1 if valid packed decimal, else 0.
int ptod (char *str, int offset, int length, int *result)
Packed decimal to decimal (int) conversion.
Return: 1 if valid packed decimal, else 0.
int ua_get_ps (long ipid)
Gather ps information (tree) for a pid.
This routine does capture the complete process tree of the system and
links processes to their ancestors and children. This, obviously, is
a UNIX specific routine. This routine is in production use under Digi-
tal UNIX, IRIX, and both Cray Unicos and Unicos/mk. An example of
usage can be found in uaklogin within the uakpacct distribution.
Use: #include ua_get_ps.h
Required extern declarations:
int uaps_cnt = 0;
struct UA_GET_PS *uaps = 0;
Return: -1 if failed, else link to first match. Note, if the the pid
was already 'found' -(link) will be returned. This is utilized for
repeated lookups on pid tree for applications like uaklogin walking
the wtmp file.
char *crypt_passwd (char *pw)
Takes a clear-text password as input and uses the crypt function ran-
domly salted to return a crypted password.
Return: crypted password string
struct passwd
*find_uid (char *userid, int *uid, char *uid_retired)
This routine provides the equivalent of getpwnam() and getpwuid() in a
single call using both the live and site-defined retired users
file(s). In addition, this function can return an available uid for
assignment to a new userid.
Attempts to find a matching user compares userid or uid uid with all
entries available via getpwent() followed by the a site defined
/etc/passwd style retired users file(s). Multiple retired users files
are space separated. If userid is null or an empty string the search
will be by uid only. If a site does not maintain a retired users
/etc/passwd format file use a null pointer for uid_retired.
If there is no matching userid and the uid was initialized as -1 then
an unused value will be assigned to uid. The extern int Min_UID,
Max_UID, and Gap_UID variables control the uid assignment range.
Assignment looks for the first free value starting with Min_UID where
there are at least Gap_UID unassigned values. The uid assignment
range is established with the first call to find_uid where uid is -1.
To reset the uid assignment range and clear the assigned uids use
'find_uid (0,0,0)'.
Required extern declarations:
int Min_UID, Max_UID, Gap_UID;
Return: null pointer if no match else matching passwd entry.
a -1 pointer if errors occured.
See getpwent().
struct tm
*yy_ddd (long julian, time_t *binary)
Argurments:
julian julian date as integer form [yy]yyddd
binary binary time (returned)
Return: (struct tm *)
like the C localtime routine or 0 if julian is invalid.
This routine is written to be generic for C under Vax/VMS and IBM/Sas.
This routine has not been tested under UNIX.
The base year and GMT offset are calculated by performing a local-
time() on 24*3600.
A more comprehensive date and time parsing routine can be found in
ua_date with the uakpacct distribution, but nobody has bothered to
generalize it yet for libcci.
struct tm
*yy_mmdd (long yymmdd, time_t *binary)
Arguments:
yymmdd date as integer form [yy]yymmdd
binary binary time (returned)
Return: (struct tm *)
like the C localtime routine or 0 if supplied yymmdd is
invalid.
This routine is written to be generic for C under Vax/VMS and IBM/Sas.
This routine has not been tested under UNIX.
A more comprehensive date and time parsing routine can be found in
ua_date with the uakpacct distribution, but nobody has bothered to
generalize it yet for libcci.
ACKNOWLEDGEMENTS
Written at the University of Alaska.