@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 - устанавливает аргумент command 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() | 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")
** (ArgumentError) 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() | 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 со значением status как лозунгом, а затем система завершает работу со статусом 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. Ключи автоматически преобразуются в строки, значения передаются как есть. nil значения удаляют заданные ключи.

@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()) :: 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() | nil

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

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

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

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

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

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

То же, что и tmp_dir/0, но выбрасывает исключение RuntimeError вместо возвращения 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() | nil

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

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

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

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

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

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

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

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