Qt 4.8
Public Functions | Static Public Functions | Properties | Friends | List of all members
QProcessEnvironment Class Reference

The QProcessEnvironment class holds the environment variables that can be passed to a program. More...

#include <qprocess.h>

Public Functions

void clear ()
 Removes all key=value pairs from this QProcessEnvironment object, making it empty. More...
 
bool contains (const QString &name) const
 Returns true if the environment variable of name name is found in this QProcessEnvironment object. More...
 
void insert (const QString &name, const QString &value)
 Inserts the environment variable of name name and contents value into this QProcessEnvironment object. More...
 
void insert (const QProcessEnvironment &e)
 Inserts the contents of e in this QProcessEnvironment object. More...
 
bool isEmpty () const
 Returns true if this QProcessEnvironment object is empty: that is there are no key=value pairs set. More...
 
QStringList keys () const
 Returns a list containing all the variable names in this QProcessEnvironment object. More...
 
bool operator!= (const QProcessEnvironment &other) const
 Returns true if this and the other QProcessEnvironment objects are different. More...
 
QProcessEnvironmentoperator= (const QProcessEnvironment &other)
 Copies the contents of the other QProcessEnvironment object into this one. More...
 
bool operator== (const QProcessEnvironment &other) const
 Returns true if this and the other QProcessEnvironment objects are equal. More...
 
 QProcessEnvironment ()
 Creates a new QProcessEnvironment object. More...
 
 QProcessEnvironment (const QProcessEnvironment &other)
 Creates a QProcessEnvironment object that is a copy of other. More...
 
void remove (const QString &name)
 Removes the environment variable identified by name from this QProcessEnvironment object. More...
 
QStringList toStringList () const
 Converts this QProcessEnvironment object into a list of strings, one for each environment variable that is set. More...
 
QString value (const QString &name, const QString &defaultValue=QString()) const
 Searches this QProcessEnvironment object for a variable identified by name and returns its value. More...
 
 ~QProcessEnvironment ()
 Frees the resources associated with this QProcessEnvironment object. More...
 

Static Public Functions

static QProcessEnvironment systemEnvironment ()
 The systemEnvironment function returns the environment of the calling process. More...
 

Properties

QSharedDataPointer< QProcessEnvironmentPrivated
 

Friends

class QProcessEnvironmentPrivate
 
class QProcessPrivate
 

Detailed Description

The QProcessEnvironment class holds the environment variables that can be passed to a program.

Note
This class or function is reentrant.
Since
4.6

A process's environment is composed of a set of key=value pairs known as environment variables. The QProcessEnvironment class wraps that concept and allows easy manipulation of those variables. It's meant to be used along with QProcess, to set the environment for child processes. It cannot be used to change the current process's environment.

The environment of the calling process can be obtained using QProcessEnvironment::systemEnvironment().

On Unix systems, the variable names are case-sensitive. For that reason, this class will not touch the names of the variables. Note as well that Unix environment allows both variable names and contents to contain arbitrary binary data (except for the NUL character), but this is not supported by QProcessEnvironment. This class only supports names and values that are encodable by the current locale settings (see QTextCodec::codecForLocale).

On Windows, the variable names are case-insensitive. Therefore, QProcessEnvironment will always uppercase the names and do case-insensitive comparisons.

On Windows CE, the concept of environment does not exist. This class will keep the values set for compatibility with other platforms, but the values set will have no effect on the processes being created.

See also
QProcess, QProcess::systemEnvironment(), QProcess::setProcessEnvironment()

Definition at line 68 of file qprocess.h.

Constructors and Destructors

◆ QProcessEnvironment() [1/2]

QProcessEnvironment::QProcessEnvironment ( )

Creates a new QProcessEnvironment object.

This constructor creates an empty environment. If set on a QProcess, this will cause the current environment variables to be removed.

Definition at line 216 of file qprocess.cpp.

217  : d(0)
218 {
219 }
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99

◆ QProcessEnvironment() [2/2]

QProcessEnvironment::QProcessEnvironment ( const QProcessEnvironment other)

Creates a QProcessEnvironment object that is a copy of other.

Definition at line 231 of file qprocess.cpp.

232  : d(other.d)
233 {
234 }
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99

◆ ~QProcessEnvironment()

QProcessEnvironment::~QProcessEnvironment ( )

Frees the resources associated with this QProcessEnvironment object.

Definition at line 224 of file qprocess.cpp.

225 {
226 }

Functions

◆ clear()

void QProcessEnvironment::clear ( )

Removes all key=value pairs from this QProcessEnvironment object, making it empty.

See also
isEmpty(), systemEnvironment()

Definition at line 295 of file qprocess.cpp.

296 {
297  if (d)
298  d->hash.clear();
299  // Unix: Don't clear d->nameMap, as the environment is likely to be
300  // re-populated with the same keys again.
301 }
void clear()
Removes all items from the hash.
Definition: qhash.h:574
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99

◆ contains()

bool QProcessEnvironment::contains ( const QString name) const

Returns true if the environment variable of name name is found in this QProcessEnvironment object.

On Windows, variable names are case-insensitive, so the key is converted to uppercase before searching. On other systems, names are case-sensitive so no trasformation is applied.

See also
insert(), value()

Definition at line 313 of file qprocess.cpp.

314 {
315  if (!d)
316  return false;
318  return d->hash.contains(d->prepareName(name));
319 }
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99
Key prepareName(const QString &name) const
Definition: qprocess_p.h:152
bool contains(const Key &key) const
Returns true if the hash contains an item with the key; otherwise returns false.
Definition: qhash.h:872

◆ insert() [1/2]

void QProcessEnvironment::insert ( const QString name,
const QString value 
)

Inserts the environment variable of name name and contents value into this QProcessEnvironment object.

If that variable already existed, it is replaced by the new value.

On Windows, variable names are case-insensitive, so this function always uppercases the variable name before inserting. On other systems, names are case-sensitive, so no transformation is applied.

On most systems, inserting a variable with no contents will have the same effect for applications as if the variable had not been set at all. However, to guarantee that there are no incompatibilities, to remove a variable, please use the remove() function.

See also
contains(), remove(), value()

Definition at line 337 of file qprocess.cpp.

Referenced by QProcessEnvironmentPrivate::fromList().

338 {
339  // our re-impl of detach() detaches from null
340  d.detach(); // detach before prepareName()
341  d->hash.insert(d->prepareName(name), d->prepareValue(value));
342 }
void detach()
If the shared data object&#39;s reference count is greater than 1, this function creates a deep copy of t...
Definition: qshareddata.h:75
Value prepareValue(const QString &value) const
Definition: qprocess_p.h:154
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99
Key prepareName(const QString &name) const
Definition: qprocess_p.h:152
iterator insert(const Key &key, const T &value)
Inserts a new item with the key and a value of value.
Definition: qhash.h:753

◆ insert() [2/2]

void QProcessEnvironment::insert ( const QProcessEnvironment e)

Inserts the contents of e in this QProcessEnvironment object.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Since
4.8

Variables in this object that also exist in e will be overwritten.

Definition at line 435 of file qprocess.cpp.

436 {
437  if (!e.d)
438  return;
439 
440  // our re-impl of detach() detaches from null
442  d->insert(*e.d);
443 }
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99
void insert(const QProcessEnvironmentPrivate &other)
Definition: qprocess.cpp:196

◆ isEmpty()

bool QProcessEnvironment::isEmpty ( ) const

Returns true if this QProcessEnvironment object is empty: that is there are no key=value pairs set.

See also
clear(), systemEnvironment(), insert()

Definition at line 283 of file qprocess.cpp.

284 {
285  // Needs no locking, as no hash nodes are accessed
286  return d ? d->hash.isEmpty() : true;
287 }
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99
bool isEmpty() const
Returns true if the hash contains no items; otherwise returns false.
Definition: qhash.h:297

◆ keys()

QStringList QProcessEnvironment::keys ( ) const

Returns a list containing all the variable names in this QProcessEnvironment object.

Since
4.8

Definition at line 417 of file qprocess.cpp.

418 {
419  if (!d)
420  return QStringList();
422  return d->keys();
423 }
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99
The QStringList class provides a list of strings.
Definition: qstringlist.h:66
QStringList keys() const
Definition: qprocess.cpp:185

◆ operator!=()

bool QProcessEnvironment::operator!= ( const QProcessEnvironment other) const
inline

Returns true if this and the other QProcessEnvironment objects are different.

See also
operator==()

Definition at line 77 of file qprocess.h.

78  { return !(*this == other); }

◆ operator=()

QProcessEnvironment & QProcessEnvironment::operator= ( const QProcessEnvironment other)

Copies the contents of the other QProcessEnvironment object into this one.

Definition at line 240 of file qprocess.cpp.

241 {
242  d = other.d;
243  return *this;
244 }
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99

◆ operator==()

bool QProcessEnvironment::operator== ( const QProcessEnvironment other) const

Returns true if this and the other QProcessEnvironment objects are equal.

Two QProcessEnvironment objects are considered equal if they have the same set of key=value pairs. The comparison of keys is done case-sensitive on platforms where the environment is case-sensitive.

See also
operator!=(), contains()

Definition at line 266 of file qprocess.cpp.

267 {
268  if (d == other.d)
269  return true;
270  if (d && other.d) {
272  return d->hash == other.d->hash;
273  }
274  return false;
275 }
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99

◆ remove()

void QProcessEnvironment::remove ( const QString name)

Removes the environment variable identified by name from this QProcessEnvironment object.

If that variable did not exist before, nothing happens.

On Windows, variable names are case-insensitive, so the key is converted to uppercase before searching. On other systems, names are case-sensitive so no trasformation is applied.

See also
contains(), insert(), value()

Definition at line 355 of file qprocess.cpp.

356 {
357  if (d) {
358  d.detach(); // detach before prepareName()
359  d->hash.remove(d->prepareName(name));
360  }
361 }
int remove(const Key &key)
Removes all the items that have the key from the hash.
Definition: qhash.h:784
void detach()
If the shared data object&#39;s reference count is greater than 1, this function creates a deep copy of t...
Definition: qshareddata.h:75
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99
Key prepareName(const QString &name) const
Definition: qprocess_p.h:152

◆ systemEnvironment()

QProcessEnvironment QProcessEnvironment::systemEnvironment ( )
static

The systemEnvironment function returns the environment of the calling process.

Since
4.6

It is returned as a QProcessEnvironment. This function does not cache the system environment. Therefore, it's possible to obtain an updated version of the environment if low-level C library functions like setenv ot putenv have been called.

However, note that repeated calls to this function will recreate the QProcessEnvironment object, which is a non-trivial operation.

See also
QProcess::systemEnvironment()

Definition at line 499 of file qprocess_unix.cpp.

Referenced by qt_create_commandline().

500 {
502 #if !defined(Q_OS_IOS)
503  const char *entry;
504  for (int count = 0; (entry = environ[count]); ++count) {
505  const char *equal = strchr(entry, '=');
506  if (!equal)
507  continue;
508 
509  QByteArray name(entry, equal - entry);
510  QByteArray value(equal + 1);
513  }
514 #endif
515  return env;
516 }
The QProcessEnvironment class holds the environment variables that can be passed to a program...
Definition: qprocess.h:68
QString value(const QString &name, const QString &defaultValue=QString()) const
Searches this QProcessEnvironment object for a variable identified by name and returns its value...
Definition: qprocess.cpp:374
The QByteArray class provides an array of bytes.
Definition: qbytearray.h:135
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99
The QString class provides a Unicode character string.
Definition: qstring.h:83
iterator insert(const Key &key, const T &value)
Inserts a new item with the key and a value of value.
Definition: qhash.h:753
const char * name
#define environ
static bool equal(const QChar *a, int l, const char *b)
Definition: qurl.cpp:3270

◆ toStringList()

QStringList QProcessEnvironment::toStringList ( ) const

Converts this QProcessEnvironment object into a list of strings, one for each environment variable that is set.

The environment variable's name and its value are separated by an equal character ('=').

The QStringList contents returned by this function are suitable for use with the QProcess::setEnvironment function. However, it is recommended to use QProcess::setProcessEnvironment instead since that will avoid unnecessary copying of the data.

See also
systemEnvironment(), QProcess::systemEnvironment(), QProcess::environment(), QProcess::setEnvironment()

Definition at line 400 of file qprocess.cpp.

401 {
402  if (!d)
403  return QStringList();
405  return d->toList();
406 }
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99
The QStringList class provides a list of strings.
Definition: qstringlist.h:66
QStringList toList() const
Definition: qprocess.cpp:150

◆ value()

QString QProcessEnvironment::value ( const QString name,
const QString defaultValue = QString() 
) const

Searches this QProcessEnvironment object for a variable identified by name and returns its value.

If the variable is not found in this object, then defaultValue is returned instead.

On Windows, variable names are case-insensitive, so the key is converted to uppercase before searching. On other systems, names are case-sensitive so no trasformation is applied.

See also
contains(), insert(), remove()

Definition at line 374 of file qprocess.cpp.

375 {
376  if (!d)
377  return defaultValue;
378 
381  if (it == d->hash.constEnd())
382  return defaultValue;
383 
384  return d->valueToString(it.value());
385 }
#define it(className, varName)
const_iterator ConstIterator
Qt-style synonym for QHash::const_iterator.
Definition: qhash.h:474
QSharedDataPointer< QProcessEnvironmentPrivate > d
Definition: qprocess.h:99
Key prepareName(const QString &name) const
Definition: qprocess_p.h:152
QString valueToString(const Value &value) const
Definition: qprocess_p.h:155
const_iterator constFind(const Key &key) const
Returns an iterator pointing to the item with the key in the hash.
Definition: qhash.h:859
const_iterator constEnd() const
Returns a const STL-style iterator pointing to the imaginary item after the last item in the hash...
Definition: qhash.h:469

Friends and Related Functions

◆ QProcessEnvironmentPrivate

Definition at line 98 of file qprocess.h.

◆ QProcessPrivate

friend class QProcessPrivate
friend

Definition at line 97 of file qprocess.h.

Properties

◆ d

QSharedDataPointer<QProcessEnvironmentPrivate> QProcessEnvironment::d
private

The documentation for this class was generated from the following files: