chiark - git - mdw - mLib/blob - env.3

   1 .\" -*-nroff-*-
   2 .TH env 3 "26 July 1999" "Straylight/Edgeware" "mLib utilities library"
   3 .SH "NAME"
   4 env \- efficient fiddling with environment variables
   5 .\" @env_get
   6 .\" @env_put
   7 .\" @env_import
   8 .\" @env_export
   9 .\" @env_destroy
  10 .SH "SYNOPSIS"
  11 .nf
  12 .B "#include <mLib/env.h>"
  13
  14 .BI "char *env_get(sym_table *" t ", const char *" name );
  15 .BI "void env_put(sym_table *" t ,
  16 .BI "             const char *" name ", const char *" value );
  17 .BI "void env_import(sym_table *" t ", char **" env );
  18 .BI "char **env_export(sym_table *" t );
  19 .fi
  20 .SH "DESCRIPTION"
  21 The functions in the
  22 .B "<mLib/env.h>"
  23 header manipulate environment variables stored in a hash table.
  24 .PP
  25 The function
  26 .B env_import
  27 reads a standard Unix environment array and stores the variables in the
  28 symbol table.  (A standard Unix environment array is an array of
  29 pointers to strings of the form
  30 .IB name = value
  31 terminated by a null pointer.  This format is used for the global
  32 .B environ
  33 variable, and by the
  34 .BR execve (2)
  35 function.)  The symbol table must have already been created (see
  36 .BR sym_create (3)).
  37 .PP
  38 The function
  39 .B env_export
  40 creates a Unix environment array from a symbol table.  The environment
  41 array is one big block of memory allocated using
  42 .BR xmalloc (3);
  43 hence, one call to
  44 .BR xfree (3)
  45 releases all the memory used for the pointer array and the strings.
  46 .PP
  47 The
  48 .B env_get
  49 function looks up a variable in an environment symbol table.  The
  50 returned result is the variable's value if it exists, or a null pointer
  51 if not.
  52 .PP
  53 The
  54 .B env_put
  55 function sets or deletes environment variables.  If the
  56 .I name
  57 argument contains an
  58 .RB ` = '
  59 character, it is assumed to be of the form
  60 .IB n = v\fR;
  61 the
  62 .I value
  63 argument is ignored, and the variable
  64 .I n
  65 is assigned the value
  66 .IR v .
  67 Otherwise, if
  68 .I value
  69 is not a null pointer, the variable
  70 .I name
  71 is assigned
  72 .IR value .
  73 Finally, if
  74 .I value
  75 is null, the variable
  76 .I name
  77 is deleted.
  78 .PP
  79 The
  80 .B env_destroy
  81 function frees an environment symbol table, together with all of the
  82 environment variables.
  83 .SH "SEE ALSO"
  84 .BR sym (3),
  85 .BR mLib (3).
  86 .SH "AUTHOR"
  87 Mark Wooding, <mdw@distorted.org.uk>