@spec argv() :: [String.t()]

Отображает аргументы командной строки.

Возвращает список аргументов командной строки, переданных программе.

@spec argv([String.t()]) :: :ok

Изменяет аргументы командной строки.

Изменяет список аргументов командной строки. Используйте с осторожностью, так как это уничтожает все предыдущие данные argv.

@spec at_exit((non_neg_integer() -> any())) :: :ok

Регистрирует обработчик завершения программы.

Регистрирует функцию, которая будет вызвана в конце скрипта Elixir. Скрипт обычно запускается через командную строку с помощью исполняемых файлов elixir и mix.

Обработчик всегда выполняется в другом процессе, чем тот, в котором он был зарегистрирован. Вследствие этого, любые ресурсы, управляемые вызывающим процессом (таблицы ETS, открытые файлы и т. д.), будут недоступны к моменту вызова функции обработчика.

Функция должна принимать код возврата в качестве аргумента.

Если VM завершается программно, с помощью System.stop/1, System.halt/1 или сигналов завершения, обратные вызовы at_exit/1 не гарантируются.

@spec build_info() :: %{
  build: String.t(),
  date: String.t(),
  revision: String.t(),
  version: String.t(),
  otp_release: String.t()
}

Информация о сборке Elixir.

Возвращает карту с версией Elixir, выпуском Erlang/OTP, с которым он был скомпилирован, коротким хэшем Git и датой и временем сборки.

Каждое значение в карте — строка, а именно:

• :build - версия Elixir, короткий хэш Git и выпуск Erlang/OTP, с которым он был скомпилирован
• :date - строковое представление даты и времени ISO8601, когда он был собран
• :otp_release - выпуск OTP, с которым он был скомпилирован
• :revision - короткий хэш Git. Если Git был недоступен во время сборки, он устанавливается в ""
• :version - версия Elixir

Не следует полагаться на конкретные форматы, возвращаемые каждым из этих полей. Вместо этого следует использовать специализированные функции, такие как version/0 для извлечения версии Elixir и otp_release/0 для извлечения выпуска Erlang/OTP.

Примеры

iex> System.build_info()
%{
  build: "1.9.0-dev (772a00a0c) (compiled with Erlang/OTP 21)",
  date: "2018-12-24T01:09:21Z",
  otp_release: "21",
  revision: "772a00a0c",
  version: "1.9.0-dev"
}

@spec cmd(binary(), [binary()], keyword()) ::
  {Collectable.t(), exit_status :: non_neg_integer()}

Выполняет данную command с args.

command ожидается как исполняемый файл, доступный в PATH, если не указан абсолютный путь.

args должен быть списком двоичных данных, которые исполняемый файл получит в качестве своих аргументов как есть. Это означает, что:

• переменные среды не будут интерполироваться
• расширение подстановок не будет происходить (если Path.wildcard/2 не используется явно)
• аргументы не нужно экранировать или заключать в кавычки для безопасности оболочки

Эта функция возвращает кортеж, содержащий собранный результат и код завершения команды.

Внутренне эта функция использует Port для взаимодействия с внешним миром. Однако, если вы планируете запустить долго выполняющуюся программу, порты гарантируют, что устройства stdin/stdout будут закрыты, но не автоматически завершат программу. Документация модуля Port описывает эту проблему и возможные решения в разделе "Зомби-процессы".

Примеры

iex> System.cmd("echo", ["hello"])
{"hello\n", 0}

iex> System.cmd("echo", ["hello"], env: [{"MIX_ENV", "test"}])
{"hello\n", 0}

Если вы хотите передавать вывод в стандартный ввод по мере его поступления:

iex> System.cmd("echo", ["hello"], into: IO.stream())
hello
{%IO.Stream{}, 0}

Если вы хотите читать строки:

iex> System.cmd("echo", ["hello\nworld"], into: [], lines: 1024)
{["hello", "world"], 0}

Параметры

• :into - вставляет результат в заданный совокупный, по умолчанию ""

• :lines - (с версии 1.15.0) читает вывод по строкам вместо байтов. Ожидает количество максимальных байтов для буферизации внутри (1024 — разумное значение по умолчанию). Совокупный вызов будет производиться с каждой завершенной строкой (независимо от размера буфера) и без символа EOL

• :cd - каталог для выполнения команды

• :env - перечисляемый список кортежей, содержащих ключи и значения переменных среды в двоичном формате. Дочерний процесс наследует все переменные среды из родительского процесса, приложения Elixir, за исключением тех, которые перезаписаны или удалены с помощью этого параметра. Установите значение nil для удаления (сброса) переменной среды, что полезно для предотвращения утечки учетных данных, переданных приложению, в дочерние процессы.

• :arg0 - устанавливает arg0 команды

• :stderr_to_stdout - перенаправляет stderr в stdout, когда true, без эффекта, если use_stdio равно false.

• :use_stdio - true по умолчанию, установка в значение false разрешает прямое взаимодействие с терминалом из вызывающего объекта.

• :parallelism - если true, VM запланирует задачи порта для повышения параллелизма в системе. Если установлено в false, VM попытается выполнить команды немедленно, улучшая задержку за счет параллелизма. По умолчанию установлено в false, и может быть установлено во время запуска системы, передав флаг +spp в --erl. Используйте :erlang.system_info(:port_parallelism) для проверки включения.

Причины ошибок

Если предоставлены неверные аргументы, ArgumentError генерируется System.cmd/3. System.cmd/3 также ожидает строгий набор параметров и будет генерировать ошибку, если предоставлены неизвестные или неверные параметры.

Кроме того, System.cmd/3 может завершиться сбоем по одной из приведенных ниже причин POSIX:

• :system_limit - все доступные порты в эмуляторе Erlang заняты

• :enomem - не хватило памяти для создания порта

• :eagain - больше нет доступных процессов операционной системы

• :enametoolong - внешняя команда была слишком длинной

• :emfile - больше нет доступных дескрипторов файлов (для процесса операционной системы, в котором работает эмулятор Erlang)

• :enfile - таблица файлов переполнена (для всей операционной системы)

• :eacces - команда не указывает на исполняемый файл

• :enoent - команда не указывает на существующий файл

Команды оболочки

Если вы хотите выполнить доверенную команду внутри оболочки с каналами, перенаправлением и т. д., пожалуйста, обратитесь к shell/2.

@spec compiled_endianness() :: :little | :big

Возвращает порядок байтов, с которым была скомпилирована система.

@spec convert_time_unit(integer(), time_unit() | :native, time_unit() | :native) ::
  integer()

Преобразует time из единиц измерения времени from_unit в единицы измерения времени to_unit.

Результат округляется с помощью функции floor.

convert_time_unit/3 принимает дополнительную единицу времени (отличную от тех, что в типе time_unit/0), называемую :native. :native — это единица измерения времени, используемая системой выполнения Erlang. Она определяется при запуске системы выполнения и остается неизменной до ее остановки, но может отличаться при следующем запуске системы выполнения на одном и том же компьютере. По этой причине вы должны использовать эту функцию для преобразования :native единиц измерения времени в предсказуемые единицы перед отображением их пользователю.

Чтобы определить, сколько секунд представляет собой :native единица в вашей текущей системе выполнения, вы можете вызвать эту функцию для преобразования 1 секунды в :native единицы измерения времени: System.convert_time_unit(1, :second, :native).

@spec cwd() :: String.t() | nil

Текущая рабочая директория.

Возвращает текущую рабочую директорию или nil если она недоступна.

@spec cwd!() :: String.t()

Текущая рабочая директория, исключение при ошибке.

Возвращает текущую рабочую директорию или вызывает исключение RuntimeError.

@spec delete_env(String.t()) :: :ok

Удаляет переменную окружения.

Удаляет переменную varname из окружения.

@spec endianness() :: :little | :big

Возвращает порядок байтов.

@spec fetch_env(String.t()) :: {:ok, String.t()} | :error

Возвращает значение заданной переменной окружения или :error если она не найдена.

Если переменная окружения varname установлена, то возвращается {:ok, value}, где value — строка. Если varname не установлена, возвращается :error.

Примеры

iex> System.fetch_env("PORT")
{:ok, "4000"}

iex> System.fetch_env("NOT_SET")
:error

@spec fetch_env!(String.t()) :: String.t()

Возвращает значение заданной переменной окружения или вызывает исключение, если она не найдена.

Аналогично get_env/1, но вызывает исключение вместо возвращения nil при отсутствии переменной.

Примеры

iex> System.fetch_env!("PORT")
"4000"

iex> System.fetch_env!("NOT_SET")
** (System.EnvError) could not fetch environment variable "NOT_SET" because it is not set

@spec find_executable(binary()) :: binary() | nil

Ищет исполняемый файл в системе.

Эта функция ищет исполняемый файл по имени, используя переменную окружения PATH в системах Windows и Unix-подобных. Она также учитывает правильное расширение исполняемых файлов для каждой операционной системы, поэтому для Windows она будет искать файлы с .com, .cmd или похожими расширениями.

@spec get_env() :: %{optional(String.t()) => String.t()}

Возвращает все переменные окружения системы.

Возвращаемое значение — это карта, содержащая пары имя-значение. Имена переменных и их значения — строки.

@spec get_env(String.t(), String.t()) :: String.t()

@spec get_env(String.t(), nil) :: String.t() | nil

Возвращает значение заданной переменной окружения.

Возвращаемое значение переменной окружения varname — строка. Если переменная окружения не установлена, возвращается строка, указанная в default или nil если не указано.

Примеры

iex> System.get_env("PORT")
"4000"

iex> System.get_env("NOT_SET")
nil

iex> System.get_env("NOT_SET", "4001")
"4001"

@spec get_pid() :: binary()

Идентификатор процесса виртуальной машины Erlang.

Возвращает идентификатор процесса текущего эмулятора Erlang в формате, обычно используемом операционной системой.

Для получения дополнительной информации, см. :os.getpid/0.

@spec halt(non_neg_integer() | binary() | :abort) :: no_return()

Немедленно завершает работу системы выполнения Erlang.

Завершает работу системы выполнения Erlang без надлежащего завершения работы приложений и портов. Обратитесь к stop/1 для аккуратного завершения работы системы.

status должно быть целым неотрицательным числом, атомом :abort или бинарным объектом.

• Если целое число, система выполнения завершается с целочисленным значением, возвращаемым операционной системе.

• Если :abort, система выполнения абортируется, создавая дамп памяти, если это включено в операционной системе.

• Если строка, создаётся дамп памяти Erlang с :abort в качестве описания, после чего система выполнения завершается со статусом 1.

Обратите внимание, что во многих платформах операционная система поддерживает только коды статуса 0-255.

Для получения дополнительной информации, см. :erlang.halt/1.

Примеры

System.halt(0)
System.halt(1)
System.halt(:abort)

@spec monotonic_time() :: integer()

Возвращает текущее монотонное время в :native единицах времени.

Это время постоянно возрастает и начинается в неопределённый момент времени. Это не строго монотонно возрастающее время. Несколько последовательных вызовов функции могут вернуть одинаковое значение.

Встраивается компилятором.

@spec monotonic_time(time_unit() | :native) :: integer()

Возвращает текущее монотонное время в заданных единицах времени.

Это время постоянно возрастает и начинается в неопределённый момент времени.

@spec no_halt() :: boolean()

Проверяет, будет ли система завершена после обработки ARGV.

@spec no_halt(boolean()) :: :ok

Помечает, должна ли система завершаться после обработки ARGV.

@spec os_time() :: integer()

Возвращает текущее время операционной системы.

Результат возвращается в :native единицах времени.

Это время может быть скорректировано вперёд или назад без ограничений и не является монотонным.

Встраивается компилятором.

@spec os_time(time_unit() | :native) :: integer()

Возвращает текущее время операционной системы в заданных единицах unit.

Это время может быть скорректировано вперёд или назад без ограничений и не является монотонным.

@spec otp_release() :: String.t()

Возвращает номер версии Erlang/OTP.

@spec pid() :: String.t()

Возвращает PID операционной системы для текущего экземпляра системы выполнения Erlang.

Возвращает строку, содержащую (обычно) числовой идентификатор процесса. В Unix-подобных системах это, как правило, значение, возвращаемое системным вызовом getpid(). В Windows используется идентификатор процесса, возвращаемый системным вызовом GetCurrentProcessId().

Примеры

System.pid()

@spec put_env(Enumerable.t()) :: :ok

Устанавливает несколько переменных окружения.

Устанавливает новое значение для каждой переменной окружения, соответствующей каждой паре {key, value} в enum. Ключи и ненулевые значения автоматически преобразуются в списки символов. Значения nil удаляют заданные ключи.

В целом, это удобная оболочка вокруг put_env/2 и delete_env/2 с поддержкой различных форматов ключей и значений.

@spec put_env(binary(), binary()) :: :ok

Устанавливает значение переменной окружения.

Устанавливает новое значение value для переменной окружения varname.

@spec restart() :: :ok

Перезапускает все приложения в системе выполнения Erlang.

Все приложения плавно завершаются, весь код выгружается, и все порты закрываются перед тем, как система снова запускает все приложения.

Примеры

System.restart()

@spec schedulers() :: pos_integer()

Возвращает количество планировщиков в виртуальной машине.

@spec schedulers_online() :: pos_integer()

Возвращает количество активных планировщиков в виртуальной машине.

@spec shell(
  binary(),
  keyword()
) :: {Collectable.t(), exit_status :: non_neg_integer()}

Выполняет заданную command в оболочке ОС.

Использует sh для систем Unix и cmd для Windows.

Примеры

iex> System.shell("echo hello")
{"hello\n", 0}

Если вы хотите передавать вывод в стандартный ввод по мере его поступления:

iex> System.shell("echo hello", into: IO.stream())
hello
{%IO.Stream{}, 0}

Параметры

Принимает те же параметры, что и cmd/3 (кроме arg0). Также принимает следующие исключающие параметры:

• :close_stdin (с версии 1.14.1) — если stdin должен быть закрыт в системах Unix, заставляя любую команду, ожидающую stdin, немедленно завершаться. По умолчанию false.

Устаревший механизм получения последнего трассировки исключения.

Всегда возвращает пустой список.

@spec stop(non_neg_integer() | binary()) :: :ok

Асинхронно и аккуратно останавливает систему выполнения Erlang.

Все приложения плавно завершаются, весь код выгружается, и все порты закрываются перед тем, как система завершается, вызвав halt/1.

status должно быть целым неотрицательным числом или бинарным.

• Если целое число, система выполнения завершается с целочисленным значением, которое возвращается операционной системе. Во многих платформах операционная система поддерживает только коды состояния 0-255.

• Если бинарный, создаётся дамп аварийного завершения Erlang со статусом в качестве слогана, а затем система выполнения завершается с кодом состояния 1.

Обратите внимание, что эта функция асинхронна, и текущий процесс будет продолжать выполнение после вызова этой функции. В случае, если вы хотите заблокировать текущий процесс до фактического завершения системы, вы можете вызвать Process.sleep(:infinity).

Примеры

System.stop(0)
System.stop(1)

@spec system_time() :: integer()

Возвращает текущее системное время в единицах измерения времени :native.

Это представление времени в виртуальной машине os_time/0. Они могут не совпадать в случае сдвигов во времени, хотя виртуальная машина стремится их согласовать. Это время не монотонно.

Встраивается компилятором.

@spec system_time(time_unit() | :native) :: integer()

Возвращает текущее системное время в заданных единицах измерения времени.

Это представление времени в виртуальной машине os_time/0. Они могут не совпадать в случае сдвигов во времени, хотя виртуальная машина стремится их согласовать. Это время не монотонно.

@spec time_offset() :: integer()

Возвращает текущий временной сдвиг между монотонным временем виртуальной машины Erlang и системным временем виртуальной машины Erlang.

Результат возвращается в единицах измерения времени :native.

См. time_offset/1 для получения дополнительной информации.

Встраивается компилятором.

@spec time_offset(time_unit() | :native) :: integer()

Возвращает текущий временной сдвиг между монотонным временем виртуальной машины Erlang и системным временем виртуальной машины Erlang.

Результат возвращается в заданных единицах измерения времени unit. Возвращённый сдвиг, добавленный к монотонному времени Erlang (например, полученному с помощью monotonic_time/1), даёт системное время Erlang, соответствующее этому монотонному времени.

@spec tmp_dir() :: String.t() | nil

Директория временных файлов для записи.

Возвращает директорию временных файлов для записи. Ищет директории в следующем порядке:

1. Директория, указанная переменной окружения TMPDIR
2. Директория, указанная переменной окружения TEMP
3. Директория, указанная переменной окружения TMP
4. C:\TMP в Windows или /tmp в Unix-подобных операционных системах
5. В качестве последнего средства, текущая рабочая директория

Возвращает nil, если ни одна из вышеперечисленных директорий не является для записи.

@spec tmp_dir!() :: String.t()

Директория временных файлов для записи, исключение при ошибке.

То же самое, что и tmp_dir/0, но вместо возвращения nil при отсутствии временной директории выбрасывает исключение RuntimeError.

@spec trap_signal(signal(), id, (-> :ok)) ::
  {:ok, id} | {:error, :already_registered} | {:error, :not_sup}
when id: term()

Перехватывает заданный signal для выполнения fun.

Можно указать необязательный id, который уникально идентифицирует функцию, иначе он генерируется автоматически. Если ранее был зарегистрирован id, эта функция возвращает кортеж ошибки. id может быть использован для удаления зарегистрированного сигнала, вызвав untrap_signal/2.

Переданная fun не принимает аргументы и должна возвращать :ok.

Возвращает {:ok, id} в случае успеха, {:error, :already_registered} в случае, если идентификатор уже зарегистрирован для данного сигнала, или {:error, :not_sup} в случае, если перехват сигналов не поддерживается текущей ОС.

В первый раз при перехвате сигнала, он переопределяет стандартное поведение операционной системы. Если тот же сигнал перехватывается несколько раз, последующие функции, переданные trap_signal, будут выполняться первыми. Другими словами, вы можете рассматривать каждую функцию как добавляемую в обработчик сигнала.

По умолчанию, Erlang VM регистрирует перехваты для трех сигналов:

• :sigstop - вежливо завершает VM с помощью stop/0
• :sigquit - останавливает VM с помощью halt/0
• :sigusr1 - останавливает VM с кодом состояния 1

Поэтому, если вы добавите перехваты для указанных выше сигналов, стандартное поведение будет выполнено после всех пользовательских сигналов.

Примечания по реализации

Все сигналы выполняются из одного процесса. Поэтому блокировка fun заблокирует последующие перехваты. Также невозможно добавлять или удалять перехваты внутри самого перехвата.

Внутренне эта функциональность построена на базе :os.set_signal/2. При регистрации перехвата Elixir автоматически устанавливает его в :handle, и он возвращается в :default, как только все перехваты будут удалены (за исключением :sigquit, :sigterm, и :sigusr1, которые всегда обрабатываются). Если вы или библиотека вызываете :os.set_signal/2 напрямую, это может отключить перехваты Elixir (или Elixir может переопределить вашу конфигурацию).

@spec unique_integer([:positive | :monotonic]) :: integer()

Генерирует и возвращает целое число, уникальное в текущей среде выполнения.

«Уникальность» означает, что эта функция, вызываемая с тем же списком modifiers, никогда не вернет одно и то же целое число более одного раза в текущей среде выполнения.

Если modifiers является [], то возвращается уникальное целое число (которое может быть положительным или отрицательным). Другие модификаторы могут быть переданы для изменения свойств возвращаемого целого числа:

• :positive - возвращаемое целое число гарантированно положительное.
• :monotonic - возвращаемое целое число монотонно возрастает. Это означает, что в той же среде выполнения (но даже в разных процессах) целые числа, возвращаемые с использованием модификатора :monotonic, всегда будут строго меньше целых чисел, возвращаемых последующими вызовами с модификатором :monotonic.

Все перечисленные выше модификаторы могут быть объединены; повторяющиеся модификаторы в modifiers будут игнорироваться.

Встраивается компилятором.

@spec untrap_signal(signal(), id) :: :ok | {:error, :not_found} when id: term()

Удаляет ранее зарегистрированный signal с id.

@spec user_home() :: String.t() | nil

Директория пользователя по умолчанию.

Возвращает домашнюю директорию пользователя (независимо от платформы).

@spec user_home!() :: String.t()

Домашняя директория пользователя, исключение при ошибке.

То же самое, что и user_home/0, но генерирует исключение RuntimeError вместо возвращения nil в случае, если домашняя директория пользователя не задана.

@spec version() :: String.t()

Информация о версии Elixir.

Возвращает информацию о версии Elixir в виде бинарного значения.