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

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for environment variable table
   4 .\"
   5 .\" (c) 1999, 2001, 2005, 2009, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH env 3mLib "26 July 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @env_get
  33 .\" @env_put
  34 .\" @env_import
  35 .\" @env_export
  36 .\" @env_destroy
  37 .
  38 .\"--------------------------------------------------------------------------
  39 .SH "NAME"
  40 env \- efficient fiddling with environment variables
  41 .
  42 .\"--------------------------------------------------------------------------
  43 .SH "SYNOPSIS"
  44 .
  45 .nf
  46 .B "#include <mLib/env.h>"
  47 .PP
  48 .BI "char *env_get(sym_table *" t ", const char *" name );
  49 .BI "void env_put(sym_table *" t ,
  50 .BI "             const char *" name ", const char *" value );
  51 .BI "void env_import(sym_table *" t ", char **" env );
  52 .BI "char **env_export(sym_table *" t );
  53 .fi
  54 .
  55 .\"--------------------------------------------------------------------------
  56 .SH "DESCRIPTION"
  57 .
  58 The functions in the
  59 .B "<mLib/env.h>"
  60 header manipulate environment variables stored in a hash table.
  61 .PP
  62 The function
  63 .B env_import
  64 reads a standard Unix environment array and stores the variables in the
  65 symbol table.  (A standard Unix environment array is an array of
  66 pointers to strings of the form
  67 .IB name = value
  68 terminated by a null pointer.  This format is used for the global
  69 .B environ
  70 variable, and by the
  71 .BR execve (2)
  72 function.)  The symbol table must have already been created (see
  73 .BR sym_create (3)).
  74 .PP
  75 The function
  76 .B env_export
  77 creates a Unix environment array from a symbol table.  The environment
  78 array is one big block of memory allocated using
  79 .BR xmalloc (3);
  80 hence, one call to
  81 .BR xfree (3)
  82 releases all the memory used for the pointer array and the strings.
  83 .PP
  84 The
  85 .B env_get
  86 function looks up a variable in an environment symbol table.  The
  87 returned result is the variable's value if it exists, or a null pointer
  88 if not.
  89 .PP
  90 The
  91 .B env_put
  92 function sets or deletes environment variables.  If the
  93 .I name
  94 argument contains an
  95 .RB ` = '
  96 character, it is assumed to be of the form
  97 .IB n = v\fR;
  98 the
  99 .I value
 100 argument is ignored, and the variable
 101 .I n
 102 is assigned the value
 103 .IR v .
 104 Otherwise, if
 105 .I value
 106 is not a null pointer, the variable
 107 .I name
 108 is assigned
 109 .IR value .
 110 Finally, if
 111 .I value
 112 is null, the variable
 113 .I name
 114 is deleted.
 115 .PP
 116 The
 117 .B env_destroy
 118 function frees an environment symbol table, together with all of the
 119 environment variables.
 120 .
 121 .\"--------------------------------------------------------------------------
 122 .SH "SEE ALSO"
 123 .
 124 .BR sym (3),
 125 .BR mLib (3).
 126 .
 127 .\"--------------------------------------------------------------------------
 128 .SH "AUTHOR"
 129 .
 130 Mark Wooding, <mdw@distorted.org.uk>
 131 .
 132 .\"----- That's all, folks --------------------------------------------------