lldb/API/SBEnvironment.h

0001 //===-- SBEnvironment.h -----------------------------------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLDB_API_SBENVIRONMENT_H
0010 #define LLDB_API_SBENVIRONMENT_H
0011
0012 #include "lldb/API/SBDefines.h"
0013
0014 namespace lldb {
0015
0016 class LLDB_API SBEnvironment {
0017 public:
0018   SBEnvironment();
0019
0020   SBEnvironment(const lldb::SBEnvironment &rhs);
0021
0022   ~SBEnvironment();
0023
0024   const lldb::SBEnvironment &operator=(const lldb::SBEnvironment &rhs);
0025
0026   /// Return the value of a given environment variable.
0027   ///
0028   /// \param [in] name
0029   ///     The name of the environment variable.
0030   ///
0031   /// \return
0032   ///     The value of the environment variable or null if not present.
0033   ///     If the environment variable has no value but is present, a valid
0034   ///     pointer to an empty string will be returned.
0035   const char *Get(const char *name);
0036
0037   /// \return
0038   ///     The number of environment variables.
0039   size_t GetNumValues();
0040
0041   /// Return the name of the environment variable at a given index from the
0042   /// internal list of environment variables.
0043   ///
0044   /// \param [in] index
0045   ///     The index of the environment variable in the internal list.
0046   ///
0047   /// \return
0048   ///     The name at the given index or null if the index is invalid.
0049   const char *GetNameAtIndex(size_t index);
0050
0051   /// Return the value of the environment variable at a given index from the
0052   /// internal list of environment variables.
0053   ///
0054   /// \param [in] index
0055   ///     The index of the environment variable in the internal list.
0056   ///
0057   /// \return
0058   ///     The value at the given index or null if the index is invalid.
0059   ///     If the environment variable has no value but is present, a valid
0060   ///     pointer to an empty string will be returned.
0061   const char *GetValueAtIndex(size_t index);
0062
0063   /// Return all environment variables contained in this object. Each variable
0064   /// is returned as a string with the following format
0065   ///     name=value
0066   ///
0067   /// \return
0068   ///     Return an lldb::SBStringList object with the environment variables.
0069   SBStringList GetEntries();
0070
0071   /// Add or replace an existing environment variable. The input must be a
0072   /// string with the format
0073   ///     name=value
0074   ///
0075   /// \param [in] name_and_value
0076   ///     The entry to set which conforms to the format mentioned above.
0077   void PutEntry(const char *name_and_value);
0078
0079   /// Update this object with the given environment variables. The input is a
0080   /// list of entries with the same format required by SBEnvironment::PutEntry.
0081   ///
0082   /// If append is false, the provided environment will replace the existing
0083   /// environment. Otherwise, existing values will be updated of left untouched
0084   /// accordingly.
0085   ///
0086   /// \param [in] entries
0087   ///     The environment variable entries.
0088   ///
0089   /// \param [in] append
0090   ///     Flag that controls whether to replace the existing environment.
0091   void SetEntries(const SBStringList &entries, bool append);
0092
0093   /// Set the value of a given environment variable.
0094   /// If the variable exists, its value is updated only if overwrite is true.
0095   ///
0096   /// \param [in] name
0097   ///     The name of the environment variable to set.
0098   ///
0099   /// \param [in] value
0100   ///     The value of the environment variable to set.
0101   ///
0102   /// \param [in] overwrite
0103   ///     Flag that indicates whether to overwrite an existing environment
0104   ///     variable.
0105   ///
0106   /// \return
0107   ///     Return whether the variable was added or modified.
0108   bool Set(const char *name, const char *value, bool overwrite);
0109
0110   /// Unset an environment variable if exists.
0111   ///
0112   /// \param [in] name
0113   ///     The name of the environment variable to unset.
0114   ///
0115   /// \return
0116   ///     Return whether a variable was actually unset.
0117   bool Unset(const char *name);
0118
0119   /// Delete all the environment variables.
0120   void Clear();
0121
0122 protected:
0123   friend class SBPlatform;
0124   friend class SBTarget;
0125   friend class SBLaunchInfo;
0126
0127   SBEnvironment(lldb_private::Environment rhs);
0128
0129   lldb_private::Environment &ref() const;
0130
0131 private:
0132   std::unique_ptr<lldb_private::Environment> m_opaque_up;
0133 };
0134
0135 } // namespace lldb
0136
0137 #endif // LLDB_API_SBENVIRONMENT_H