SETKEY_LONG(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