libs/envvar.h

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