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 distributed with uak and partially distributed as
libc19 with uac19.
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_ar2_get,
ua_arg_show, ua_ar2_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 util-
ities which were converted later to UNIX. A number of programs utilize these rou-
tines, including those included in the uak, uakpacct, and uaio packages under
ftp://ftp.alaska.edu/pub/sois/
Reference the comments in routine source and the supplied programs as examples 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 | ua_ar2_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_Q long comment
UA_Arg_A argument (parameter)
UA_Arg_Z argument (parameter), variable amount
UA_Arg_F flag
UA_Ar2_F hidden flage (ua_ar2_get only)
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
UA_Ar2_L long integer (ua_ar2_get only)
UA_Ar2_Y floating number (ua_ar2_get only)
This is the primary routine of cci command parser utilized by non-UNIX oper-
ating 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 irrele-
vant.
Return: 0 or action
int ua_arg_show | ua_ar2_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 recon-
structed removing removing consecutive delimiters and replacing them with a
NULL. The resulting string is a series of strings with the return indicat-
ing 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 as will white space before the delimiter.
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 spe-
cific routine. This routine is in production use under Digital UNIX, IRIX,
and both Cray Unicos and Unicos/mk. An example of usage can be found in
uaklogin within the uakpacct distribution.
Note, this routine has been retired in favor of uaps_get() now included in
the uakpacct distribution. The newer uaps_get() is much more effective for
parsing ps output and has been validated on Linux, Solaris, SuperUX (NEC),
and AIX.
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 randomly
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 sin-
gle 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 localtime() 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. Ongoing maintenance via SourceForge by Denali
Sun Consulting.
Suggestions or bug reports can be directed to denalisun907@gmail.com.