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

   1 .\" -*-nroff-*-
   2 .TH env 3 "26 July 1999" mLib
   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 malloc (3);
  43 hence, one call to
  44 .BR free (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 argument is ignored, and the variable
  63 .I n
  64 is assigned the value
  65 .IR v .
  66 Otherwise, if
  67 .I value
  68 is not a null pointer, the variable
  69 .I name
  70 is assigned the value
  71 .I value .
  72 Finally, if
  73 .I value
  74 is null, the variable
  75 .I name
  76 is deleted.
  77 .PP
  78 The
  79 .B env_destroy
  80 function frees all the memory used by an environment symbol table.  The
  81 table itself is destroyed too.
  82 .SH "SEE ALSO"
  83 .BR sym (3),
  84 .BR mLib (3).
  85 .SH "AUTHOR"
  86 Mark Wooding, <mdw@nsict.org>