@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}

Параметры

• :into — вставляет результат в заданный коллектор, по умолчанию ""
• :cd — каталог для выполнения команды
• :env — перечислимый набор кортежей, содержащих имя-значение переменной окружения в бинарном формате. Дочерний процесс наследует все переменные среды от родительского процесса, приложения Elixir, за исключением тех, которые перезаписаны или очищены с помощью этого параметра. Укажите значение nil для очистки (снятия) переменной среды, что полезно для предотвращения утечки учетных данных, переданных в приложение, в дочерние процессы.
• :arg0 — устанавливает аргумент команды arg0
• :stderr_to_stdout — перенаправляет stderr в stdout, когда true
• :parallelism — когда true, VM будет планировать задачи порта для повышения параллелизма в системе. Если установлено false, VM будет пытаться выполнить команды немедленно, улучшая задержку за счет параллелизма. Значение по умолчанию может быть установлено при запуске системы, передав аргумент "+spp" в --erl.

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

Если предоставлены недопустимые аргументы, 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()

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

Возвращает текущий рабочий каталог или поднимает RuntimeError.

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

Текущий рабочий каталог.

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

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

Удаляет переменную среды.

Удаляет переменную varname из среды.

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

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

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

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

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

Примеры

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

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

@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 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() | 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, система прерывается с созданием дампа памяти (core dump), если это разрешено в операционной системе.

• Если строка, создаётся дамп сбоя Erlang со статусом в качестве слогана, а затем система завершается со статусом 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()) :: integer()

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

Это время постоянно возрастает и начинается в не указанную точку времени.

@spec no_halt() :: boolean()

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

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

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

@spec os_time() :: integer()

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

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

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

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

@spec os_time(time_unit()) :: 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.

@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.

Важно: Используйте эту функцию с осторожностью. В частности, никогда не передавайте недоверенные данные пользователя в эту функцию, так как пользователь сможет выполнить "атаку с внедрением команд", выполнив любой код непосредственно на компьютере. В общем случае, предпочтительнее использовать cmd/3 вместо этой функции.

Примеры

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

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

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

Параметры

Принимает те же параметры, что и cmd/3, за исключением arg0.

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

Начиная с Erlang/OTP 23, эта функция всегда возвращает пустой список.

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

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

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

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

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

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

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

Примеры

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

@spec system_time() :: integer()

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

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

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

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

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

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

@spec time_offset() :: integer()

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

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

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

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

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

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

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

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

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

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

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

Директория временного хранения с правом записи.

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

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

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

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

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

Важно: Перехват сигналов может иметь серьёзные последствия для работы и поведения системы в производстве, поэтому крайне не рекомендуется библиотекам устанавливать собственные перехваты. Вместо этого они должны перенаправлять пользователей на самостоятельную настройку. Единственные случаи, когда библиотекам разрешено устанавливать собственные перехваты, это использование Elixir в режиме сценариев, например, в файлах .exs и через задачи Mix.

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

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

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

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

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

• :sigstop - плавно завершает ВМ с stop/0
• :sigquit - останавливает ВМ через halt/0
• :sigusr1 - останавливает ВМ со статусом кода 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()

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

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

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

Директория домашней папки пользователя.

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

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

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

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