@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 описывает эту проблему и возможные решения в разделе "Процессы-зомби".

Разделение аргументов в Windows и недоверенные аргументы

В системах Unix аргументы передаются новому процессу операционной системы как массив строк, а в Windows от дочернего процесса требуется их парсинг, и некоторые программы Windows могут применять свои собственные правила, которые несовместимы со стандартным парсингом argv в C.

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

Поэтому, если вы работаете в Windows и выполняете пакетные файлы или приложения .com, вы не должны передавать недоверенный ввод в качестве аргументов программе. Вы можете избежать случайного выполнения, явно указав расширение исполняемого файла, такой как .exe, и убедиться, что программа на самом деле не является пакетным файлом или приложением .com.

Примеры

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 - задает аргумент command 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 с статусом в качестве слогана, а затем система завершается со значением статуса 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() | :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.

Внимание

Используйте эту функцию с осторожностью. В частности, никогда не передавайте недоверенные данные пользователя в эту функцию, так как пользователь сможет выполнить "атаки с подстановкой команд", выполнив любой код непосредственно на машине. В общем случае, предпочтительнее использовать 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). Также принимает следующие эксклюзивные параметры:

• :close_stdin (с версии v1.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()) :: 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() | 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.

Избегайте установки перехватов в библиотеках

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

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

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

В случае успеха возвращается {:ok, id}, {:error, :not_sup} в случае, если идентификатор уже зарегистрирован для данного сигнала, или {: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() | nil

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

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

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

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

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

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

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

Возвращает версию Elixir как строку.