SETKEY_SHORT(3)
NAME
deletekey, findkey, freekeylist, getkeytype, getkey_any,
getkey_str, getkey_byte, getkey_ubyte, getkey_short,
getkey_ushort, getkey_int, getkey_uint, getkey_long,
getkey_ulong, getkey_float, getkey_double, getkey_flag,
getkey_fileptr, getkey_time, keyiterate, add_keys,
delete_keys, newkeylist, setkey, setkey_str, setkey_byte,
setkey_ubyte, setkey_short, setkey_ushort, setkey_int,
setkey_uint, setkey_long, setkey_ulong, setkey_float,
setkey_double, setkey_fileptr, setkey_time, key_strdup
-a set of functions to create and manipulate keylists
SYNOPSIS
#include <soi_sds.h>
extern void add_keys (KEY *inlist, KEY **tolist);
extern void deletekey (KEY **list, char *key);
extern void delete_keys (KEY *inlist, KEY **fromlist);
extern KEY *findkey (KEY *list, char *key);
extern void freekeylist (KEY **list);
extern int getkeytype (KEY *list, char *key);
extern void getkey_any (KEY *list, char *key, void *valptr);
extern char *getkey_str (KEY *list, char *key);
extern FILE *getkey_fileptr (KEY *list, char *key);
extern int getkey_byte (KEY *list, char *key);
extern int getkey_short (KEY *list, char *key);
extern int getkey_int (KEY *list, char *key);
extern long getkey_long (KEY *list, char *key);
extern unsigned int getkey_ubyte (KEY *list, char *key);
extern unsigned int getkey_ushort (KEY *list, char *key);
extern unsigned int getkey_uint (KEY *list, char *key);
extern unsigned long getkey_ulong (KEY *list, char *key);
extern int getkey_flag (KEY *list, char *key);
extern double getkey_float (KEY *list, char *key);
extern double getkey_double (KEY *list, char *key);
extern TIME getkey_time (KEY *list, char *key);
extern void keyiterate (void (*action)(), KEY *overlist);
extern KEY *newkeylist ();
extern void setkey (KEY **list, char *key, void *val, int type);
extern void setkey_str (KEY **list, char *key, char *val);
extern void setkey_fileptr (KEY **list, char *key, FILE *val);
extern void setkey_byte (KEY **list, char *key, char val);
extern void setkey_short (KEY **list, char *key, short val);
extern void setkey_int (KEY **list, char *key, int val);
extern void setkey_long (KEY **list, char *key, long val);
extern void setkey_ubyte (KEY **list, char *key, unsigned char val);
extern void setkey_ushort (KEY **list, char *key, unsigned short val);
extern void setkey_uint (KEY **list, char *key, unsigned int val);
extern void setkey_ulong (KEY **list, char *key, unsigned long val);
extern void setkey_float (KEY **list, char *key, float val);
extern void setkey_double (KEY **list, char *key, double val);
extern void setkey_time (KEY **list, char *key, TIME val);
extern char *key_strdup (char *str);
DESCRIPTION
A keylist is a data structure which provides a way to pass
messages between levels in the 4-level module model, for
example between interface-level and strategy-level func-
tions. A keylist is a set of entries (or elements), each of
which contain a key name, a value, and the type of the
value. The key name is a string which is unique in the set.
That is, there cannot be more than one element in a keylist
with the same key name. The valid types for values are
defined in soi_keys.h.
newkeylist creates an empty keylist.
findkey returns a pointer to the entry in a keylist with the
specified key name or, if there is no entry with the speci-
fied key name, returns a NULL pointer.
getkey has been superseded by getkey_any.
getkey_any ensures that valptr references the value in the
keylist associated with key name. This function is not
recommended because any misuse of valptr after the call can
destroy the integrity of the keylist. Use of specific get-
key_ functions such as getkey_str is recommended instead.
If there is no entry with the specified key name the error
condition is set and the value referenced by valptr is
unchanged. This function does not return a value.
getkey_str returns a pointer to a malloced copy of the value
in the list associated with the specified key name. If
there is no entry with the specified key name or if the type
is not KEYTYP_STR, a NULL pointer is returned.
getkey_fileptr returns the value in the list associated with
the specified key name. Note that this value is a pointer.
If there is no entry with the specified key name or if the
type is not KEYTYP_FILEPTR, a NULL pointer is returned.
getkey_XXX where XXX is not str or fileptr returns the value
in the list associated with the specified key name. If there
is no entry with the specified key name or if the type does
not correspond to XXX, soi_errno is set and a noticeable
value is returned (NaN or a very large or small integer).
The keytype does not have to match the selected keytype
exactly, but must be consistent. Thus, getkey_byte,
getkey_ubyte, getkey_short, getkey_ushort, and getkey_int
return an int if the keytype matches any of those types, and
getkey_float and getkey_double return a double if the
keytype is float or double. getkey_uint returns an unsigned
int if the value is non-negative. getkey_long and
getkey_ulong behave analogously, but they assume that longs
are longer than ints. getkey_flag is synonymous with
getkey_int.
getkeytype returns the type of an entry with the specified
keyname in the list. If there is no entry with the speci-
fied key name, getkeytype returns KEYTYP_VOID.
setkey provides a way to add entries to a keylist. After
successful completion of a call to setkey, the list contains
an entry with the specified key name, value, and type. Any
previously existing entry with the same key name is lost.
If the call is unsuccessful, the list is unchanged.
setkey_XXX is similar to setkey except that the type is
determined by XXX.
deletekey deletes an entry with the specified key name from
a keylist or, if there is no entry with the specified key
name, leaves the keylist unchanged.
delete_keys deletes the entries in one list from the entries
in a second list. The first list is unchanged.
freekeylist frees the memory associated with the list.
keyiterate performs the given action on each entry in the
list. No order is guaranteed. The calling function provides
the function which acts on a keylist entry.
add_keys adds the entries in one list to the entries in a
second list. Any entry in the second list which had the
same key name as an entry in the first list is lost. The
first list is unchanged.
key_strdup returns a malloced copy of the specified string.
EXAMPLES
See ~soi/(version)/src/cmd/main.c,
~soi/(version)/src/examples/*.c,
~soi/(version)/src/modules/noop.c, and
~soi/(version)/src/libast.d/names.c
FILES
~soi/(version)/include/soi_key.h
SEE ALSO
"Programming in the SOI Analysis Environment", SOI TN 93-107
DIAGNOSTICS
none
BUGS
getkey_str is most often used in strategy modules to fetch
parameter values. Because the command line module interface
has the capability to define parameters recursively in terms
of other parameters, getkey_str may return unexpected
values. This potentially dangerous feature of the command
line module interface was originally intended to specify
input and output and is noted in the man page for module.
For example, if the value for a parameter "in" is "/foo/"
and the default value for a parameter "out" is "in", the
parameter value for "out" will be "/foo/".
getkey_XXX where XXX is not str returns a misleading value
when the call is unsuccessful. To avoid this problem use
getkeytype to confirm the existence of the the entry in the
list and to determine the type before making the call to
getkey_XXX.
getkey_long will return a wrong value if the keytype is an
unsigned int and longs are not longer than ints.
There is no special function for setting or returning values
associated with file pointer types. Use setkey and getkey.
There should be a supported "Time" type.
HISTORY
10-Sep-93 Kay Leibrand: created for SOI v 0.7.
1994-02-08 SOI Version 0.8