base-4.18.1.0: Basic libraries

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | provisional
Portability | portable
Safe Haskell | Safe
Language | Haskell2010

System.Environment

Description

Miscellaneous information about the system environment.

Synopsis

- getArgs :: IO [String]
- getProgName :: IO String
- executablePath :: Maybe (IO (Maybe FilePath))
- getExecutablePath :: IO FilePath
- getEnv :: String -> IO String
- lookupEnv :: String -> IO (Maybe String)
- setEnv :: String -> String -> IO ()
- unsetEnv :: String -> IO ()
- withArgs :: [String] -> IO a -> IO a
- withProgName :: String -> IO a -> IO a
- getEnvironment :: IO [(String, String)]

# Documentation

getArgs :: IO [String] Source #

Computation `getArgs` returns a list of the program's command line arguments (not including the program name).

getProgName :: IO String Source #

Computation `getProgName` returns the name of the program as it was invoked.

However, this is hard-to-impossible to implement on some non-Unix OSes, so instead, for maximum portability, we just return the leafname of the program as invoked. Even then there are some differences between platforms: on Windows, for example, a program invoked as foo is probably really `FOO.EXE`, and that is what `getProgName` will return.

executablePath :: Maybe (IO (Maybe FilePath)) Source #

Get an action to query the absolute pathname of the current executable.

If the operating system provides a reliable way to determine the current executable, return the query action, otherwise return `Nothing`. The action is defined on FreeBSD, Linux, MacOS, NetBSD, and Windows.

Even where the query action is defined, there may be situations where no result is available, e.g. if the executable file was deleted while the program is running. Therefore the result of the query action is a `Maybe FilePath`.

Note that for scripts and interactive sessions, the result is the path to the interpreter (e.g. ghci.)

Note also that while most operating systems return `Nothing` if the executable file was deleted/unlinked, some (including NetBSD) return the original path.

Since: base-4.17.0.0

getExecutablePath :: IO FilePath Source #

Returns the absolute pathname of the current executable, or `argv[0]` if the operating system does not provide a reliable way query the current executable.

Note that for scripts and interactive sessions, this is the path to the interpreter (e.g. ghci.)

Since base 4.11.0.0, `getExecutablePath` resolves symlinks on Windows. If an executable is launched through a symlink, `getExecutablePath` returns the absolute path of the original executable.

If the executable has been deleted, behaviour is ill-defined and varies by operating system. See `executablePath` for a more reliable way to query the current executable.

Since: base-4.6.0.0

getEnv :: String -> IO String Source #

Computation `getEnv` `var` returns the value of the environment variable `var`. For the inverse, the `setEnv` function can be used.

This computation may fail with:

- `isDoesNotExistError` if the environment variable does not exist.

lookupEnv :: String -> IO (Maybe String) Source #

Return the value of the environment variable `var`, or `Nothing` if there is no such value.

For POSIX users, this is equivalent to `getEnv`.

Since: base-4.6.0.0

setEnv :: String -> String -> IO () Source #

`setEnv name value` sets the specified environment variable to `value`.

Early versions of this function operated under the mistaken belief that setting an environment variable to the empty string on Windows removes that environment variable from the environment. For the sake of compatibility, it adopted that behavior on POSIX. In particular

    setEnv name ""

has the same effect as

    unsetEnv name

If you'd like to be able to set environment variables to blank strings, use `setEnv`.

Throws `IOException` if `name` is the empty string or contains an equals sign.

Since: base-4.7.0.0

unsetEnv :: String -> IO () Source #

`unsetEnv name` removes the specified environment variable from the environment of the current process.

Throws `IOException` if `name` is the empty string or contains an equals sign.

Since: base-4.7.0.0

withArgs :: [String] -> IO a -> IO a Source #

`withArgs` `args act` - while executing action `act`, have `getArgs` return `args`.

withProgName :: String -> IO a -> IO a Source #

`withProgName` `name act` - while executing action `act`, have `getProgName` return `name`.

getEnvironment :: IO [(String, String)] Source #

`getEnvironment` retrieves the entire environment as a list of `(key,value)` pairs.

If an environment entry does not contain an `'='` character, the `key` is the whole entry and the `value` is the empty string.