libs/envvar.h

   1 /* -*-c-*- */
   2 #ifndef FVWMLIB_ENVVAR_H
   3 #define FVWMLIB_ENVVAR_H
   4
   5 /*
   6  *  SYNOPSIS      #include "envvar.h"
   7  *                int envExpand(char *s, int maxstrlen);
   8  *
   9  *  INPUT         s       string to expand environment variables in.
  10  *                maxstrlen     max length of string, including '\0'.
  11  *
  12  *  OUTPUT        s       the string with environment variables expanded.
  13  *
  14  *  RETURNS       Number of changes done.
  15  *
  16  *  NOTES         A non-existing variable is substituted with the empty
  17  *                string.
  18  *
  19  */
  20 int envExpand(char *s, int maxstrlen);
  21
  22 /*
  23  *  FUNCTION      Expand environment variables into a new string.
  24  *
  25  *  SYNOPSIS      #include "envvar.h"
  26  *                char *envDupExpand(const char *s, int extra);
  27  *
  28  *  INPUT         s       string to expand environment variables in.
  29  *                extra   number of extra bytes to allocate in the
  30  *                        string, in addition to the string contents
  31  *                        and the terminating '\0'.
  32  *
  33  *  RETURNS       A dynamically allocated string with environment
  34  *                variables expanded.
  35  *                Use free() to deallocate the buffer when it is no
  36  *                longer needed.
  37  *                NULL is returned if there is not enough memory.
  38  *
  39  *  NOTES         A non-existing variable is substituted with the empty
  40  *                string.
  41  *
  42  */
  43 char *envDupExpand(const char *s, int extra);
  44
  45 /*
  46  *  FUNCTION      Search for the first environment variable and return
  47  *                its contents and coordinates in the given string.
  48  *
  49  *  INPUT         s       the string to scan.
  50  *                        may include $ and { } that introduce variable.
  51  *
  52  *  OUTPUT        beg     index in the string of matching $.
  53  *                end     index in the string, first after matching var.
  54  *
  55  *  RETURNS       The variable contents; "" if env variable has legal name,
  56  *                but does not exist; or NULL if no env variables found.
  57  *                Returned constant string must not be deallocated.
  58  *
  59  *  NOTE          This function will only return `legal' variables. There
  60  *                may be $'s in the string that are not followed by what
  61  *                is considered a legal variable name introducer. Such
  62  *                occurrences are skipped.
  63  *                If nothing is found returns NULL and sets beg and end to 0.
  64  *
  65  *  EXAMPLE       getFirstEnv("echo $HOME/.fvwm/config", &beg, &end)
  66  *                returns "/home/username" and beg=5, end=10.
  67  *
  68  */
  69 const char* getFirstEnv(const char *s, int *beg, int *end);
  70
  71 /* This function keeps a list of all strings that were set in the environment.
  72  * If a variable is written again, the old memory is freed.  This function
  73  * should be called instead of putenv().
  74  *
  75  *   var - environement variable name
  76  *   env - environment string ("variable=value")
  77  *
  78  * Both arguments are copied internally and should be freed after calling this
  79  * function.
  80  */
  81 void flib_putenv(char *var, char *env);
  82
  83 /* Replacement for unsetenv(). */
  84 void flib_unsetenv(const char *name);
  85
  86
  87 #endif