1 //===-- SBEnvironment.h -----------------------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLDB_API_SBENVIRONMENT_H 10 #define LLDB_API_SBENVIRONMENT_H 11 12 #include "lldb/API/SBDefines.h" 13 14 namespace lldb { 15 16 class LLDB_API SBEnvironment { 17 public: 18 SBEnvironment(); 19 20 SBEnvironment(const lldb::SBEnvironment &rhs); 21 22 ~SBEnvironment(); 23 24 const lldb::SBEnvironment &operator=(const lldb::SBEnvironment &rhs); 25 26 /// Return the value of a given environment variable. 27 /// 28 /// \param [in] name 29 /// The name of the environment variable. 30 /// 31 /// \return 32 /// The value of the environment variable or null if not present. 33 /// If the environment variable has no value but is present, a valid 34 /// pointer to an empty string will be returned. 35 const char *Get(const char *name); 36 37 /// \return 38 /// The number of environment variables. 39 size_t GetNumValues(); 40 41 /// Return the name of the environment variable at a given index from the 42 /// internal list of environment variables. 43 /// 44 /// \param [in] index 45 /// The index of the environment variable in the internal list. 46 /// 47 /// \return 48 /// The name at the given index or null if the index is invalid. 49 const char *GetNameAtIndex(size_t index); 50 51 /// Return the value of the environment variable at a given index from the 52 /// internal list of environment variables. 53 /// 54 /// \param [in] index 55 /// The index of the environment variable in the internal list. 56 /// 57 /// \return 58 /// The value at the given index or null if the index is invalid. 59 /// If the environment variable has no value but is present, a valid 60 /// pointer to an empty string will be returned. 61 const char *GetValueAtIndex(size_t index); 62 63 /// Return all environment variables contained in this object. Each variable 64 /// is returned as a string with the following format 65 /// name=value 66 /// 67 /// \return 68 /// Return an lldb::SBStringList object with the environment variables. 69 SBStringList GetEntries(); 70 71 /// Add or replace an existing environment variable. The input must be a 72 /// string with the format 73 /// name=value 74 /// 75 /// \param [in] name_and_value 76 /// The entry to set which conforms to the format mentioned above. 77 void PutEntry(const char *name_and_value); 78 79 /// Update this object with the given environment variables. The input is a 80 /// list of entries with the same format required by SBEnvironment::PutEntry. 81 /// 82 /// If append is false, the provided environment will replace the existing 83 /// environment. Otherwise, existing values will be updated of left untouched 84 /// accordingly. 85 /// 86 /// \param [in] entries 87 /// The environment variable entries. 88 /// 89 /// \param [in] append 90 /// Flag that controls whether to replace the existing environment. 91 void SetEntries(const SBStringList &entries, bool append); 92 93 /// Set the value of a given environment variable. 94 /// If the variable exists, its value is updated only if overwrite is true. 95 /// 96 /// \param [in] name 97 /// The name of the environment variable to set. 98 /// 99 /// \param [in] value 100 /// The value of the environment variable to set. 101 /// 102 /// \param [in] overwrite 103 /// Flag that indicates whether to overwrite an existing environment 104 /// variable. 105 /// 106 /// \return 107 /// Return whether the variable was added or modified. 108 bool Set(const char *name, const char *value, bool overwrite); 109 110 /// Unset an environment variable if exists. 111 /// 112 /// \param [in] name 113 /// The name of the environment variable to unset. 114 /// 115 /// \return 116 /// Return whether a variable was actually unset. 117 bool Unset(const char *name); 118 119 /// Delete all the environment variables. 120 void Clear(); 121 122 protected: 123 friend class SBPlatform; 124 friend class SBTarget; 125 friend class SBLaunchInfo; 126 127 SBEnvironment(lldb_private::Environment rhs); 128 129 lldb_private::Environment &ref() const; 130 131 private: 132 std::unique_ptr<lldb_private::Environment> m_opaque_up; 133 }; 134 135 } // namespace lldb 136 137 #endif // LLDB_API_SBENVIRONMENT_H 138