Система

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

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

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

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

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

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

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

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

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

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

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

Если виртуальная машина завершает работу программно, посредством 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 — (с версии v1.15.0) читает вывод по строкам вместо байтов. Ожидает число максимальных байтов для буферизации внутри (1024 — разумное значение по умолчанию). Коллектор будет вызываться с каждой завершённой строкой (независимо от размера буфера) и без символа EOL

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

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

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

• :stderr_to_stdout — перенаправляет stderr в stdout, когда true

• :parallelism — при true виртуальная машина запланирует задачи порта для повышения параллельности в системе. Если установлено значение false, виртуальная машина попытается выполнить команды немедленно, повышая задержку ценой параллельности. По умолчанию 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()

Возвращает идентификатор процесса операционной системы для текущего экземпляра системы выполнения 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) - если входной поток должен быть закрыт в системах Unix, заставляя любую команду, ожидающую входной поток, немедленно завершить работу. По умолчанию 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, но выбрасывает 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 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 — возвращаемое целое число гарантированно будет положительным.
• :positive — возвращаемое целое число монотонно возрастает. Это означает, что в одной и той же инстанции выполнения (но даже в разных процессах) целые числа, возвращаемые с модификатором :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, но вместо возвращения nil при отсутствии домашней папки пользователя генерирует исключение RuntimeError.

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

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

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

@spec wait_until_booted() :: :ok

Ожидает загрузки системы.

Вызов этой функции блокирует выполнение, пока не будут обработаны все элементы ARGV. В релизе это означает, что обработан сценарий запуска и ARGV. Это полезно только для тех, кто реализует пользовательские оболочки/консоли поверх Elixir.

Однако будьте осторожны, не вызывайте эту команду из процесса, обрабатывающего аргументы командной строки, так как это приведёт к тупику.