gcc/fortran/doc/gfortran/intrinsic-procedures/getenvironmentvariable.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: GET_ENVIRONMENT_VARIABLE, environment variable
   7
   8 .. _get_environment_variable:
   9
  10 GET_ENVIRONMENT_VARIABLE --- Get an environmental variable
  11 **********************************************************
  12
  13 .. function:: GET_ENVIRONMENT_VARIABLE(NAME, VALUE, LENGTH, STATUS, TRIM_NAME)
  14
  15   Get the :samp:`{VALUE}` of the environmental variable :samp:`{NAME}`.
  16
  17   :param NAME:
  18     Shall be a scalar of type ``CHARACTER``
  19     and of default kind.
  20
  21   :param VALUE:
  22     (Optional) Shall be a scalar of type ``CHARACTER``
  23     and of default kind.
  24
  25   :param LENGTH:
  26     (Optional) Shall be a scalar of type ``INTEGER``
  27     and of default kind.
  28
  29   :param STATUS:
  30     (Optional) Shall be a scalar of type ``INTEGER``
  31     and of default kind.
  32
  33   :param TRIM_NAME:
  34     (Optional) Shall be a scalar of type ``LOGICAL``
  35     and of default kind.
  36
  37   :return:
  38     Stores the value of :samp:`{NAME}` in :samp:`{VALUE}`. If :samp:`{VALUE}` is
  39     not large enough to hold the data, it is truncated. If :samp:`{NAME}`
  40     is not set, :samp:`{VALUE}` will be filled with blanks. Argument :samp:`{LENGTH}`
  41     contains the length needed for storing the environment variable :samp:`{NAME}`
  42     or zero if it is not present. :samp:`{STATUS}` is -1 if :samp:`{VALUE}` is present
  43     but too short for the environment variable; it is 1 if the environment
  44     variable does not exist and 2 if the processor does not support environment
  45     variables; in all other cases :samp:`{STATUS}` is zero. If :samp:`{TRIM_NAME}` is
  46     present with the value ``.FALSE.``, the trailing blanks in :samp:`{NAME}`
  47     are significant; otherwise they are not part of the environment variable
  48     name.
  49
  50   Standard:
  51     Fortran 2003 and later
  52
  53   Class:
  54     Subroutine
  55
  56   Syntax:
  57     .. code-block:: fortran
  58
  59       CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)
  60
  61   Example:
  62     .. code-block:: fortran
  63
  64       PROGRAM test_getenv
  65         CHARACTER(len=255) :: homedir
  66         CALL get_environment_variable("HOME", homedir)
  67         WRITE (*,*) TRIM(homedir)
  68       END PROGRAM