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 programs utilize these routines, 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 (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 delim-
iters 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 delimiter. Null fields can be defined by adjacent delim-
iters.
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 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 func-
tion 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 getp-
wuid() 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). Multi-
ple 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 unas-
signed 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.