Spec-Zone.ru › Perl 5.38

perlapi

СОДЕРЖАНИЕ

  • ИМЯ
  • ОПИСАНИЕ
  • Обработка AV
  • Функции обратного вызова
  • Приведение типов
  • Изменение регистра символов
  • Классификация символов
  • Информация о компиляторе и препроцессоре
  • Директивы компилятора
  • Временные хуки области видимости
  • Конкурентность
  • COP и хеши подсказок
  • Пользовательские операторы
  • Обработка CV
  • Отладка
  • Функции вывода
  • Встраивание, потоки и клонирование интерпретатора
  • Errno
  • Макросы обработки исключений (простые)
  • Значения конфигурации файловой системы
  • Числа с плавающей точкой
  • Общая конфигурация
    • Список символов свойств HAS_foo
    • Список символов, требуемых #include
  • Глобальные переменные
  • Обработка GV и стеки
  • Манипулирование хуками
  • Обработка HV
  • Ввод/Вывод
  • Целые числа
  • Форматы ввода/вывода
  • Интерфейс лексера
  • Локали
  • Магия
  • Управление памятью
  • MRO
  • Функции multicall
  • Числовые функции
  • Optrees
  • Упаковка и распаковка
  • Структуры данных Pad
  • Доступ к паролям и группам
  • Пути к системным командам
  • Информация о прототипах
  • Функции REGEXP
  • Отчеты и форматы
  • Сигналы
  • Конфигурация сайта
  • Значения конфигурации сокетов
  • Фильтры исходного кода
  • Макросы манипуляции стеком
  • Обработка строк
  • Флаги SV
  • Обработка SV
  • Загрязнение
  • Время
  • Имена typedef
  • Поддержка Юникода
  • Вспомогательные функции
  • Версионирование
  • Предупреждения и завершение
  • XS
  • Недокументированные элементы
  • АВТОРЫ
  • СМОТРИ ТАКЖЕ

ИМЯ

perlapi - автоматически сгенерированная документация для общедоступного API Perl

ОПИСАНИЕ

Этот файл содержит большую часть документации общедоступного API Perl, сгенерированной инструментом embed.pl. В частности, это список функций, макросов, флагов и переменных, которые могут использоваться авторами расширений. Помимо perlintern и config.h, некоторые элементы здесь указаны как фактически документированные в другом pod.

В конце представлен список функций, которые ещё не задокументированы. Заявки на исправление приветствуются! Интерфейсы этих функций могут быть изменены без предварительного уведомления.

Некоторые из задокументированных функций объединены, так что одна запись служит для нескольких функций, которые выполняют в основном то же самое, но с небольшими различиями. Например, одна форма может обрабатывать магию, а другая — нет. Название каждой разновидности указано в верхней части одной записи. Но если все имеют одинаковую сигнатуру (аргументы и возвращаемый тип), за исключением их имён, отображается только использование базовой формы. Если любая из форм имеет другую сигнатуру (например, возвращает const или нет), сигнатура каждой функции отображается явно.

Все, что не указано здесь или в других упомянутых pod, не является частью общедоступного API и вообще не должно использоваться авторами расширений. По этим причинам следует избегать слепого использования функций, перечисленных в proto.h, при написании расширений.

В Perl, в отличие от C, строка символов может обычно содержать встроенные NUL символы. Иногда в документации строка Perl называется «буфером», чтобы отличить её от строки C, но иногда и те, и другие просто называются строками.

Обратите внимание, что все глобальные переменные API Perl должны быть ссылаются с префиксом PL_. Снова, те, что не перечислены здесь, не должны использоваться авторами расширений и могут быть изменены или удалены без предварительного уведомления; то же самое относится к макросам. Некоторые макросы предоставлены для совместимости со старыми, неформатированными именами, но эта поддержка может быть отключена в будущих выпусках.

Первоначально Perl был написан для обработки только US-ASCII (то есть символы, порядковые номера которых находятся в диапазоне 0—127). И документация и комментарии всё ещё могут использовать термин ASCII, когда фактически подразумевается весь диапазон от 0 до 255.

Символы вне ASCII, ниже 256, могут иметь различные значения, в зависимости от различных факторов. (См., в частности, perllocale.) Но обычно весь диапазон можно обозначить как ISO-8859-1. Часто используется термин «Latin-1» (или «Latin1») как эквивалент ISO-8859-1. Но некоторые люди рассматривают «Latin1» как относящийся только к символам в диапазоне от 128 до 255, или иногда от 160 до 255. Эта документация использует «Latin1» и «Latin-1» для обозначения всех 256 символов.

Обратите внимание, что Perl может быть скомпилирован и запущен как под ASCII, так и под EBCDIC (см. perlebcdic). Большая часть документации (и даже комментарии в коде) игнорирует возможность EBCDIC. Для почти всех целей различия прозрачны. Например, под EBCDIC вместо UTF-8 используется UTF-EBCDIC для кодирования строк Unicode, и поэтому всякий раз, когда эта документация относится к utf8 (и вариантам этого имени, включая в именах функций), это также (по сути, прозрачно) означает UTF-EBCDIC. Но порядковые номера символов отличаются между ASCII, EBCDIC и UTF-кодировками, а строка, закодированная в UTF-EBCDIC, может занимать другое количество байтов, чем в UTF-8.

Структура этого документа предварительная и может быть изменена. Предложения и исправления приветствуются perl5-porters@perl.org.

Разделы этого документа в настоящее время:

"Обработка AV"
"Функции обратного вызова"
"Приведение типов"
"Изменение регистра символов"
"Классификация символов"
"Информация о компиляторе и препроцессоре"
"Директивы компилятора"
"Обработчики области видимости во время компиляции"
"Конкурентность"
"COPы и хэш-таблицы подсказок"
"Пользовательские операторы"
"Обработка CV"
"Отладка"
"Функции отображения"
"Встраивание, потоки и клонирование интерпретатора"
"Errno"
"Макросы обработки исключений (простые)"
"Значения конфигурации файловой системы"
"Числа с плавающей точкой"
"Общая конфигурация"
"Глобальные переменные"
"Обработка GV и стеков"
"Управление хуками"
"Обработка HV"
"Ввод/вывод"
"Целые числа"
"Форматы ввода/вывода"
"Интерфейс лексического анализатора"
"Локали"
"Магия"
"Управление памятью"
"MRO"
"Функции множественного вызова"
"Числовые функции"
"Optrees"
"Кодирование и декодирование"
"Структуры данных с заполнителями"
"Доступ к паролям и группам"
"Пути к системным командам"
"Информация о прототипах"
"Функции REGEXP"
"Отчёты и форматы"
"Сигналы"
"Конфигурация сайта"
"Значения конфигурации сокетов"
"Фильтры исходного кода"
"Макросы управления стеком"
"Обработка строк"
"Флаги SV"
"Обработка SV"
"Загрязнение"
"Время"
"Имена typedef"
"Поддержка Unicode"
"Вспомогательные функции"
"Версионирование"
"Предупреждения и завершение работы"
"XS"
"Недокументированные элементы"

Ниже приведён список в алфавитном порядке, без учёта регистра.

Обработка AV

AV

Описание в perlguts.

AvALLOC

Описание в perlguts.

AvALLOC(AV* av)
AvARRAY

Возвращает указатель на внутренний массив SV* AV.

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

SV**  AvARRAY(AV* av)
av_clear

Освобождает все элементы массива, оставляя его пустым. Эквивалент функции @array = () в XS. Смотрите также "av_undef".

Обратите внимание, что действия деструктора, вызываемого прямо или косвенно при освобождении элемента массива, могут привести к уменьшению счётчика ссылок самого массива (например, при удалении записи в таблице символов). Поэтому существует вероятность, что AV будет освобождён (или даже перевыделен) по возвращении из вызова, если у вас нет ссылки на него.

void  av_clear(AV *av)
av_count

Возвращает количество элементов в массиве av. Это фактическая длина массива, включая все неопределённые элементы. Она всегда совпадает с av_top_index(av) + 1.

Size_t  av_count(AV *av)
av_create_and_push

Добавляет SV в конец массива, создавая массив при необходимости. Небольшая внутренняя вспомогательная функция для исключения дублирования кода.

ПРИМЕЧАНИЕ: av_create_and_push необходимо явно вызвать как Perl_av_create_and_push с параметром aTHX_. 

void  Perl_av_create_and_push(pTHX_ AV ** const avp,
                              SV * const val)
av_create_and_unshift_one

Вставляет SV в начало массива, создавая массив при необходимости. Небольшая внутренняя вспомогательная функция для исключения дублирования кода.

ПРИМЕЧАНИЕ: av_create_and_unshift_one необходимо явно вызвать как Perl_av_create_and_unshift_one с параметром aTHX_. 

SV **  Perl_av_create_and_unshift_one(pTHX_ AV ** const avp,
                                      SV * const val)
av_delete

Удаляет элемент с индексом key из массива, делает элемент смертельным и возвращает его. Если flags равно G_DISCARD, элемент освобождается и возвращается NULL. NULL также возвращается, если key выходит за пределы диапазона.

Эквивалент в Perl: splice(@myarray, $key, 1, undef) (в контексте void, если splice присутствует).

SV *  av_delete(AV *av, SSize_t key, I32 flags)
av_exists

Возвращает true, если элемент с индексом key был инициализирован.

Это основано на том, что неинициализированные элементы массива устанавливаются в NULL.

Эквивалент в Perl: exists($myarray[$key]).

bool  av_exists(AV *av, SSize_t key)
av_extend

Предварительно расширяет массив, чтобы он мог хранить значения с индексами 0..key. Таким образом, av_extend(av,99) гарантирует, что массив может хранить 100 элементов, т.е. av_store(av, 0, sv) по av_store(av, 99, sv) в обычном массиве будет работать без дополнительного выделения памяти.

Если аргумент av является связанным массивом, то будет вызван метод связанного массива EXTEND с аргументом (key+1).

void  av_extend(AV *av, SSize_t key)
av_fetch

Возвращает SV по указанному индексу в массиве. key - это индекс. Если lval истинно, вы гарантированно получите реальный SV (если он раньше не был реальным), который вы сможете изменить. Проверьте, что возвращаемое значение не NULL, прежде чем ссылаться на него как на SV*.

См. "Понимание магии связанных хэшей и массивов" в perlguts для получения дополнительной информации о работе с связанными массивами с помощью этой функции.

Приблизительный эквивалент в Perl: $myarray[$key].

SV **  av_fetch(AV *av, SSize_t key, I32 lval)
AvFILL

То же, что "av_top_index" или "av_tindex".

SSize_t  AvFILL(AV* av)
av_fill

Устанавливает индекс самого большого элемента массива в заданное число, эквивалент Perl $#array = $fill;.

Количество элементов в массиве будет fill + 1 после выполнения av_fill(). Если массив был короче, то добавленные элементы устанавливаются в NULL. Если массив был длиннее, то лишние элементы освобождаются. av_fill(av, -1) совпадает с av_clear(av).

void  av_fill(AV *av, SSize_t fill)
av_len

То же, что "av_top_index". Обратите внимание, что, в отличие от того, что подразумевает название, он возвращает максимальный индекс в массиве. Это отличается от "sv_len", который возвращает ожидаемое значение.

Для получения фактического количества элементов в массиве используйте "av_count".

SSize_t  av_len(AV *av)
av_make

Создаёт новый AV и заполняет его списком (**strp, длина size) SV. Для каждого SV создаётся копия, поэтому их счётчики ссылок не изменяются. Новый AV будет иметь счётчик ссылок 1.

Эквивалент в Perl: my @new_array = ($scalar1, $scalar2, $scalar3...);

AV *  av_make(SSize_t size, SV **strp)
av_pop

Удаляет один SV из конца массива, уменьшая его размер на единицу и возвращая SV (передавая контроль одной ссылке) вызывающему коду. Возвращает &PL_sv_undef если массив пуст.

Эквивалент в Perl: pop(@myarray);

SV *  av_pop(AV *av)
av_push

Добавляет SV (передавая контроль одной ссылке) в конец массива. Массив автоматически увеличится, чтобы вместить добавление.

Эквивалент в Perl: push @myarray, $val;.

void  av_push(AV *av, SV *val)
av_push_simple

Это упрощенная версия av_push, предполагающая, что массив прост — без магических свойств, без только для чтения и AvREAL — и что key не меньше -1. Эту функцию НЕЛЬЗЯ использовать в ситуациях, где эти предположения могут не выполняться.

Добавляет SV (передавая управление одним счётчиком ссылок) в конец массива. Массив автоматически увеличится, чтобы вместить добавление.

Аналог на Perl: push @myarray, $val;.

void  av_push_simple(AV *av, SV *val)
av_shift

Удаляет один SV из начала массива, уменьшая его размер на единицу и возвращая SV (передавая управление одним счётчиком ссылок) вызывающей стороне. Возвращает &PL_sv_undef если массив пуст.

Аналог на Perl: shift(@myarray);

SV *  av_shift(AV *av)
av_store

Сохраняет SV в массиве. Индекс массива задаётся как key. Значение возврата будет NULL если операция завершилась неудачно или если значение не нужно было фактически сохранять в массиве (например, в случае связанных массивов). В противном случае оно может быть обработано для получения сохранённого SV*, который был там (= val)

Обратите внимание, что вызывающая сторона отвечает за надлежащее увеличение счётчика ссылок val перед вызовом и уменьшение его, если функция вернула NULL.

Приблизительный аналог на Perl: splice(@myarray, $key, 1, $val).

См. "Understanding the Magic of Tied Hashes and Arrays" в perlguts для получения дополнительной информации о использовании этой функции с связанными массивами.

SV **  av_store(AV *av, SSize_t key, SV *val)
av_tindex
av_top_index

Эти функции ведут себя идентично. Если массив av пуст, они возвращают -1; в противном случае они возвращают максимальное значение индексов всех элементов массива, которые в настоящее время определены в av.

Они обрабатывают магию 'get'.

Аналог на Perl для этих функций: $#av.

Используйте "av_count" для получения количества элементов в массиве.

SSize_t  av_tindex(AV *av)
av_undef

Удаляет массив. Аналог XS функции undef(@array).

Помимо освобождения всех элементов массива (как и av_clear()), эта функция также освобождает память, используемую av для хранения списка скаляров.

См. "av_clear" для примечания о том, что массив может быть недействительным после возврата.

void  av_undef(AV *av)
av_unshift

Добавляет указанное количество undef значений в начало массива. Массив автоматически увеличится, чтобы вместить добавление.

Аналог на Perl: unshift @myarray, ((undef) x $num);

void  av_unshift(AV *av, SSize_t num)
get_av

Возвращает AV указанного глобального или пакетного массива Perl с заданным именем (так что это не будет работать с лексическими переменными). flags передаются в gv_fetchpv. Если GV_ADD установлено и переменная Perl не существует, она будет создана. Если flags равно нулю (игнорируя SVf_UTF8) и переменная не существует, возвращается NULL.

Аналог на Perl: @{"$name"}.

ПРИМЕЧАНИЕ: форма perl_get_av() устарела.

AV *  get_av(const char *name, I32 flags)
newAV
newAV_alloc_x
newAV_alloc_xz

Все эти функции создают новый AV, устанавливая счётчик ссылок в 1. Если вам также известны начальные элементы массива, см. "av_make".

В качестве справки, массив состоит из трёх частей:

  1. Структура данных, содержащая информацию о массиве в целом, такую как его размер и счётчик ссылок.

  2. Массив языка C, содержащий указатели на отдельные элементы. Эти элементы обрабатываются как указатели на SV, поэтому все они должны быть приводимыми к типу SV*.

  3. Сами отдельные элементы. Это могут быть, например, SV и/или AV и/или HV и т. д.

Пустому массиву требуется только первая структура данных, и все эти функции создают её. Они различаются тем, что ещё они делают, как показано ниже:

newAV форма

Это не делает ничего, кроме создания структуры данных всего массива. Приблизительный аналог на Perl: my @array;

Это полезно, когда минимальный размер массива может быть нулевым (возможно, есть пути кода, которые полностью пропустят его использование).

Если массив используется, структура данных указателей должна быть выделена в этот момент. Это будет сделано функцией "av_extend">, либо явно:

av_extend(av, len);

или неявно при сохранении первого элемента:

(void)av_store(av, 0, sv);

Неиспользуемые элементы массива обычно инициализируются av_extend.

newAV_alloc_x форма

Это фактически выполняет newAV и также выделяет (неинициализированное) место для массива указателей. Это используется, когда вы заранее знаете вероятный минимальный размер массива. Эффективнее сделать это, чем выполнять обычный newAV за которым следует av_extend.

Конечно, массив можно расширить в случае необходимости.

size должно быть не меньше 1.

newAV_alloc_xz форма

Это то же самое, что и newAV_alloc_x, но инициализирует каждый указатель в нём значением NULL. Это обеспечивает дополнительную безопасность, предотвращая чтение элементов до их установки.

size должно быть не меньше 1.

Следующие примеры приводят к массиву, который может вместить четыре элемента (индексы 0 .. 3):

AV *av = newAV();
av_extend(av, 3);

AV *av = newAV_alloc_x(4);

AV *av = newAV_alloc_xz(4);

В отличие от этого, следующие примеры выделяют массив, который гарантированно вмещает только один элемент без расширения:

AV *av = newAV_alloc_x(1);
AV *av = newAV_alloc_xz(1);
AV *  newAV         ()
AV *  newAV_alloc_x (SSize_t size)
AV *  newAV_alloc_xz(SSize_t size)
newAVav

Создаёт новый AV и заполняет его значениями, скопированными из существующего AV. Новый AV будет иметь счётчик ссылок 1 и будет содержать новые SV, скопированные из исходного SV. Исходный источник останется неизменным.

Аналог на Perl: my @new_array = @existing_array;

AV *  newAVav(AV *oav)
newAVhv

Создаёт новый AV и заполняет его ключами и значениями, скопированными из существующего HV. Новый AV будет иметь счётчик ссылок 1 и будет содержать новые SV, скопированные из исходного HV. Исходный источник останется неизменным.

Аналог на Perl: my @new_array = %existing_hash;

AV *  newAVhv(HV *ohv)
Nullav

DEPRECATED! Планируется удалить Nullav из будущих релизов Perl. Не используйте его в новом коде; удалите его из существующего кода.

Указатель на пустой AV.

(устарело — используйте (AV *)NULL вместо этого)

Функции обратного вызова

call_argv

Выполняет обратный вызов указанной именованной и пакетной подпрограмме Perl с argv (массивом строк, завершённым NULL) в качестве аргументов. См. perlcall.

Приблизительный аналог на Perl: &{"$sub_name"}(@$argv).

ПРИМЕЧАНИЕ: форма perl_call_argv() устарела.

I32  call_argv(const char *sub_name, I32 flags, char **argv)
call_method

Выполняет обратный вызов указанному методу Perl. Объект с указанием благословления должен быть в стеке. См. perlcall.

ПРИМЕЧАНИЕ: форма perl_call_method() устарела.

I32  call_method(const char *methname, I32 flags)
call_pv

Выполняет обратный вызов указанной Perl подпрограмме. См. perlcall.

ПРИМЕЧАНИЕ: форма perl_call_pv() устарела.

I32  call_pv(const char *sub_name, I32 flags)
call_sv

Выполняет обратный вызов Perl-подпрограмме, указанной в SV.

Если ни флаг G_METHOD, ни флаг G_METHOD_NAMED не указаны, SV может быть любым из CV, GV, ссылкой на CV, ссылкой на GV или SvPV(sv) будет использоваться как имя вызываемой подпрограммы.

Если указан флаг G_METHOD, SV может быть ссылкой на CV или SvPV(sv) будет использоваться как имя вызываемого метода.

Если указан флаг G_METHOD_NAMED, SvPV(sv) будет использоваться как имя вызываемого метода.

Другие значения обрабатываются специально для внутреннего использования и на них не следует полагаться.

См. perlcall.

ПРИМЕЧАНИЕ: форма perl_call_sv() устарела.

I32  call_sv(SV *sv, volatile I32 flags)
DESTRUCTORFUNC_NOCONTEXT_t

Описание в perlguts.

DESTRUCTORFUNC_t

Описание в perlguts.

ENTER

Открывающая скобка при обратном вызове. См. "LEAVE" и perlcall.

ENTER;
ENTER_with_name

То же, что и "ENTER", но при включённом отладчике также связывает указанную строковую литерал с новым пространством имён.

ENTER_with_name("name");
eval_pv

Приводит Perl к eval заданной строке в скалярном контексте и возвращает результат SV*.

ПРИМЕЧАНИЕ: форма perl_eval_pv() устарела.

SV *  eval_pv(const char *p, I32 croak_on_error)
eval_sv

Приводит Perl к eval строке в SV. Поддерживает те же флаги, что и call_sv, за исключением очевидного исключения G_EVAL. См. perlcall.

Флаг G_RETHROW может использоваться, если вам нужно только выполнить код eval_sv(), определённый строкой, но не обрабатывать ошибки.

ПРИМЕЧАНИЕ: форма perl_eval_sv() устарела.

I32  eval_sv(SV *sv, I32 flags)
FREETMPS

Закрывающая скобка для временных переменных при обратном вызове. См. "SAVETMPS" и perlcall.

FREETMPS;
G_DISCARD

Описание в perlcall.

G_EVAL

Описание в perlcall.

GIMME

DEPRECATED! Планируется удалить GIMME из будущих версий Perl. Не используйте его в новом коде; удалите его из существующего кода.

Обратно совместимая версия GIMME_V, которая может возвращать только G_SCALAR или G_LIST; в контексте void она возвращает G_SCALAR. Устарело. Используйте GIMME_V вместо этого.

U32  GIMME
GIMME_V

Эквивалент XSUB-функции в Perl для wantarray. Возвращает G_VOID, G_SCALAR или G_LIST для контекста void, скаляр или список соответственно. См. perlcall для примера использования.

U32  GIMME_V
G_KEEPERR

Описание в perlcall.

G_LIST

Описание в perlcall.

G_NOARGS

Описание в perlcall.

G_SCALAR

Описание в perlcall.

G_VOID

Описание в perlcall.

is_lvalue_sub

Возвращает ненулевое значение, если подпрограмма, вызывающая эту функцию, вызывается в контексте lvalue. В противном случае возвращает 0.

I32  is_lvalue_sub()
LEAVE

Закрывающая скобка для обратного вызова. См. "ENTER" и perlcall.

LEAVE;
LEAVE_with_name

То же, что и "LEAVE", но при включенном отладке сначала проверяет, что область имеет заданное имя. name должно быть строкой.

LEAVE_with_name("name");
MORTALDESTRUCTOR_SV

Описание в perlguts.

MORTALDESTRUCTOR_SV(SV *coderef, SV *args)
mortal_destructor_sv

Эта функция организует вызов либо Perl-ссылок на код, либо ссылок на C-функции в конце текущей команды.

Аргумент coderef определяет тип вызываемой функции. Если это SvROK(), предполагается, что это ссылка на CV, и будет организован вызов coderef. Если это не SvROK(), то предполагается, что это SvIV(), которая является SvIOK(), значением которой является указатель на C-функцию типа DESTRUCTORFUNC_t, созданную с помощью PTR2INT(). В любом случае, параметр args будет передан в обратный вызов в качестве параметра, хотя правила выполнения этого отличаются между режимами Perl и C. Обычно эта функция используется только напрямую для случая Perl, а обёртка mortal_destructor_x() используется для случая C-функции.

При работе в режиме обратного вызова Perl параметр args может быть NULL, в этом случае ссылка на код вызывается без аргументов. В противном случае, если это AV (SvTYPE(args) == SVt_PVAV), содержимое AV будет использовано в качестве аргументов для ссылки на код, а если это любой другой тип, то SV args будет предоставлен в качестве единственного аргумента для ссылки на код.

При работе в режиме обратного вызова C параметр args будет передан непосредственно C-функции как указатель void *. Дополнительная обработка аргумента не будет выполняться, и ответственность за освобождение параметра args лежит на вызывающей стороне.

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

void  mortal_destructor_sv(SV *coderef, SV *args)
MORTALDESTRUCTOR_X

Описание в perlguts.

MORTALDESTRUCTOR_X(DESTRUCTORFUNC_t f, SV *sv)
PL_errgv

Описание в perlcall.

save_aelem
save_aelem_flags

Эти функции сохраняют значение элемента массива av[idx] для восстановления в конце окружающего псевдоблока.

В save_aelem, SV в C**sptr> будет заменён на новый скаляр undef. Этот скаляр унаследует все магические свойства исходного **sptr, и все магические свойства «set» будут обработаны.

В save_aelem_flags, установленное значение SAVEf_KEEPOLDELEM в flags заставляет функцию отказаться от всех этих действий: скаляр в **sptr остаётся неизменным. Если SAVEf_KEEPOLDELEM не установлено, SV в C**sptr> будет заменён на новый скаляр undef. Этот скаляр унаследует все магические свойства исходного **sptr. Магические свойства «set» будут обработаны только в том случае, если SAVEf_SETMAGIC установлено в flags. 

void  save_aelem      (AV *av, SSize_t idx, SV **sptr)
void  save_aelem_flags(AV *av, SSize_t idx, SV **sptr,
                       const U32 flags)
save_aptr

Описание в perlguts.

void  save_aptr(AV **aptr)
save_ary

Описание в perlguts.

AV *  save_ary(GV *gv)
SAVEBOOL

Описание в perlguts.

SAVEBOOL(bool i)
SAVEDELETE

Описание в perlguts.

SAVEDELETE(HV * hv, char * key, I32 length)
SAVEDESTRUCTOR

Описание в perlguts.

SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)
SAVEDESTRUCTOR_X

Описание в perlguts.

SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)
SAVEFREEOP

Описание в perlguts.

SAVEFREEOP(OP *op)
SAVEFREEPV

Описание в perlguts.

SAVEFREEPV(char *pv)
SAVEFREERCPV

Описание в perlguts.

SAVEFREERCPV(char *pv)
SAVEFREESV

Описание в perlguts.

SAVEFREESV(SV* sv)
SAVEGENERICSV

Описание в perlguts.

SAVEGENERICSV(char **psv)
save_hash

Описание в perlguts.

HV *  save_hash(GV *gv)
save_helem
save_helem_flags

Эти функции сохраняют значение элемента хэша (в Perlish-терминах) $hv{key}] для восстановления в конце окружающего псевдоблока.

В save_helem, SV в C**sptr> будет заменён на новый скаляр undef. Этот скаляр унаследует все магические свойства исходного **sptr, и все магические свойства «set» будут обработаны.

В save_helem_flags, установленное значение SAVEf_KEEPOLDELEM в flags заставляет функцию отказаться от всех этих действий: скаляр в **sptr остаётся неизменным. Если SAVEf_KEEPOLDELEM не установлено, SV в C**sptr> будет заменён на новый скаляр undef. Этот скаляр унаследует все магические свойства исходного **sptr. Магические свойства «set» будут обработаны только в том случае, если SAVEf_SETMAGIC установлено в flags. 

void  save_helem      (HV *hv, SV *key, SV **sptr)
void  save_helem_flags(HV *hv, SV *key, SV **sptr,
                       const U32 flags)
save_hptr

Описание в perlguts.

void  save_hptr(HV **hptr)
SAVEINT

Описание в perlguts.

SAVEINT(int i)
save_item

Описание в perlguts.

void  save_item(SV *item)
SAVEIV

Описание в perlguts.

SAVEIV(IV i)
SAVEI8

Описание в perlguts.

SAVEI8(I8 i)
SAVEI16

Описание в perlguts.

SAVEI16(I16 i)
SAVEI32

Описание в perlguts.

SAVEI32(I32 i)
SAVELONG

Описание в perlguts.

SAVELONG(long i)
SAVEMORTALIZESV

Описание в perlguts.

SAVEMORTALIZESV(SV* sv)
SAVEPPTR

Описание в perlguts.

SAVEPPTR(char * p)
SAVERCPV

Описание в perlguts.

SAVERCPV(char *pv)
save_scalar

Описание в perlguts.

SV *  save_scalar(GV *gv)
SAVESPTR

Описание в perlguts.

SAVESPTR(SV * s)
SAVESTACK_POS

Описание в perlguts.

SAVESTACK_POS()
SAVESTRLEN

Описание в perlguts.

SAVESTRLEN(STRLEN i)
save_svref

Описание в perlguts.

SV *  save_svref(SV **sptr)
SAVETMPS

Открывающая скобка для временных значений в обратном вызове. См. "FREETMPS" и perlcall.

SAVETMPS;

Преобразование типов

Atof

Это синоним для "my_atof".

NV  Atof(NN const char * const s)
cBOOL

Преобразование в булево значение. Когда Perl можно было скомпилировать на компиляторах до C99, преобразование (bool) не обязательно выполнялось правильно, поэтому была создана эта макрокоманда (и она была сделана несколько сложной, чтобы обойти ошибки старых компиляторов). Сейчас, много лет спустя, и используется C99, это больше не требуется, но сохраняется для обратной совместимости.

bool  cBOOL(bool expr)
INT2PTR

Описание в perlguts.

type  INT2PTR(type, int value)
I_V

Преобразование NV в IV, избегая неопределённого поведения C

IV  I_V(NV what)
I_32

Преобразование NV в I32, избегая неопределённого поведения C

I32  I_32(NV what)
PTR2IV

Описание в perlguts.

IV  PTR2IV(void * ptr)
PTR2nat

Описание в perlguts.

IV  PTR2nat(void *)
PTR2NV

Описание в perlguts.

NV  PTR2NV(void * ptr)
PTR2ul

Описание в perlguts.

unsigned long  PTR2ul(void *)
PTR2UV

Описание в perlguts.

UV  PTR2UV(void * ptr)
PTRV

Описание в perlguts.

U_V

Преобразование NV в UV, избегая неопределённого поведения C

UV  U_V(NV what)
U_32

Преобразование NV в U32, избегая неопределённого поведения C

U32  U_32(NV what)

Изменение регистра символов

Perl использует полные отображения регистров Юникода. Это означает, что преобразование одного символа в другой регистр может привести к последовательности из более чем одного символа. Например, заглавная буква ß (ЛАТИНСКАЯ МАЛЕНЬКАЯ БУКВА РЕЗКОЕ С) — это последовательность из двух символов SS. Это создаёт некоторые сложности. Строчные буквы всех символов в диапазоне 0..255 — это один символ, и поэтому "toLOWER_L1" предоставляется. Но toUPPER_L1 не может существовать, так как не мог бы возвращать допустимый результат для всех законных входных данных. Вместо этого "toUPPER_uvchr" имеет API, который позволяет возвращать все возможные допустимые результаты. Аналогичным образом здесь не реализована ни одна другая функция, которая ограничена тем, что не может дать правильные результаты для всего диапазона возможных входных данных.

toFOLD
toFOLD_A
toFOLD_utf8
toFOLD_utf8_safe
toFOLD_uvchr

Все эти функции возвращают преобразованный символ в нижний регистр. «Преобразование в нижний регистр» — это внутренний регистр для /i сопоставления шаблонов. Если преобразованные в нижний регистр символы A и B совпадают, они совпадают без учёта регистра; в противном случае они не совпадают.

Различия в формах определяют, над какой областью они работают, и указывают, задаётся ли входной параметр как код символа (формы с параметром cp) или как строка UTF-8 (другие формы). В последнем случае используемый код символа — это первый в буфере кодов символов, закодированных в UTF-8, определяемый аргументами p .. e - 1.

toFOLD и toFOLD_A являются синонимами друг друга. Они возвращают преобразованный в нижний регистр символ любого символа ASCII-диапазона. В этом диапазоне преобразование в нижний регистр идентично преобразованию в нижний регистр. Все остальные входные данные возвращаются без изменений. Поскольку это макросы, тип входных данных может быть любым целым, а выходные данные будут занимать такое же количество битов, что и входные.

Нет toFOLD_L1 и toFOLD_LATIN1, так как преобразование в нижний регистр некоторых кодов символов в диапазоне 0..255 находится за пределами этого диапазона или состоит из нескольких символов. Используйте вместо этого toFOLD_uvchr.

toFOLD_uvchr возвращает преобразованный в нижний регистр символ любого символа Юникода. Возвращаемое значение идентично значению toFOLD_A для входных символов в диапазоне ASCII. Преобразование в нижний регистр подавляющего большинства символов Юникода совпадает с самим символом. Для таких символов и символов, которые находятся за пределами допустимого максимального значения Юникода, эта функция возвращает входной символ без изменений. Кроме того, она сохраняет UTF-8 результата в буфер, начинающийся с s, а его длину в байтах в *lenp. Вызывающая функция должна сделать s достаточно большим, чтобы содержать не менее UTF8_MAXBYTES_CASE+1 байт, чтобы избежать возможного переполнения.

ПРИМЕЧАНИЕ: преобразование в нижний регистр символа может содержать более одного символа. Возвращаемое значение этой функции — только первый из них. Весь преобразованный символ в нижний регистр возвращается в s. Чтобы определить, состоит ли результат из более чем одного символа, можно сделать следующее:

uc = toFOLD_uvchr(cp, s, &len);
if (len > UTF8SKIP(s)) { is multiple code points }
else { is a single code point }

toFOLD_utf8 и toFOLD_utf8_safe являются синонимами друг друга. Единственное различие между этими функциями и toFOLD_uvchr заключается в том, что исходный код этих функций закодирован в UTF-8, а не представляет собой код символа. Он передаётся как буфер, начинающийся с p, причём e указывает на байт за концом буфера. Буфер p может содержать более одного символа; но исследуется только первый (до e - 1). Если UTF-8 входного символа некорректен каким-либо образом, программа может прерваться, или функция может вернуть ЗАМЕЩАЮЩИЙ СИМВОЛ по усмотрению реализации и с возможными изменениями в будущих выпусках.

UV  toFOLD          (UV cp)
UV  toFOLD_A        (UV cp)
UV  toFOLD_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toFOLD_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toFOLD_uvchr    (UV cp, U8* s, STRLEN* lenp)
toLOWER
toLOWER_A
toLOWER_LATIN1
toLOWER_LC
toLOWER_L1
toLOWER_utf8
toLOWER_utf8_safe
toLOWER_uvchr

Все эти функции возвращают строчную форму символа. Различия заключаются в области действия и в том, задаётся ли входной параметр как код символа (формы с параметром cp) или как строка UTF-8 (другие формы). В последнем случае используемый код символа — это первый в буфере кодов символов, закодированных в UTF-8, определяемый аргументами p .. e - 1.

toLOWER и toLOWER_A являются синонимами друг друга. Они возвращают строчную форму символа любого символа ASCII-диапазона в верхнем регистре. Все остальные входные данные возвращаются без изменений. Поскольку это макросы, тип входных данных может быть любым целым, а выходные данные будут занимать такое же количество битов, что и входные.

toLOWER_L1 и toLOWER_LATIN1 являются синонимами друг друга. Они ведут себя так же, как toLOWER для входных данных ASCII-диапазона. Но также возвращают строчную форму символа любого символа в верхнем регистре в диапазоне 0..255, предполагая кодировку Latin-1 (или эквивалент EBCDIC на таких платформах).

toLOWER_LC возвращает строчную форму входного символа согласно правилам текущего локали POSIX. Входные символы за пределами диапазона 0..255 возвращаются без изменений.

toLOWER_uvchr возвращает строчную форму любого символа Юникода. Возвращаемое значение идентично значению toLOWER_L1 для входных символов в диапазоне 0..255. Строчная форма подавляющего большинства символов Юникода совпадает с самим символом. Для таких символов и символов, которые находятся за пределами допустимого максимального значения Юникода, эта функция возвращает входной символ без изменений. Кроме того, она сохраняет UTF-8 результата в буфер, начинающийся с s, а его длину в байтах в *lenp. Вызывающая функция должна сделать s достаточно большим, чтобы содержать не менее UTF8_MAXBYTES_CASE+1 байт, чтобы избежать возможного переполнения.

ПРИМЕЧАНИЕ: строчная форма символа может содержать более одного символа. Возвращаемое значение этой функции — только первый из них. Весь строчный символ возвращается в s. Чтобы определить, состоит ли результат из более чем одного символа, можно сделать следующее:

uc = toLOWER_uvchr(cp, s, &len);
if (len > UTF8SKIP(s)) { is multiple code points }
else { is a single code point }

toLOWER_utf8 и toLOWER_utf8_safe являются синонимами друг друга. Единственное различие между этими функциями и toLOWER_uvchr заключается в том, что исходный код этих функций закодирован в UTF-8, а не представляет собой код символа. Он передаётся как буфер, начинающийся с p, причём e указывает на байт за концом буфера. Буфер p может содержать более одного символа; но исследуется только первый (до e - 1). Если UTF-8 входного символа некорректен каким-либо образом, программа может прерваться, или функция может вернуть ЗАМЕЩАЮЩИЙ СИМВОЛ по усмотрению реализации и с возможными изменениями в будущих выпусках.

UV  toLOWER          (UV cp)
UV  toLOWER_A        (UV cp)
UV  toLOWER_LATIN1   (UV cp)
UV  toLOWER_LC       (UV cp)
UV  toLOWER_L1       (UV cp)
UV  toLOWER_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toLOWER_uvchr    (UV cp, U8* s, STRLEN* lenp)
toTITLE
toTITLE_A
toTITLE_utf8
toTITLE_utf8_safe
toTITLE_uvchr

Все эти функции возвращают заглавную форму символа. Различия заключаются в области действия и в том, задаётся ли входной параметр как код символа (формы с параметром cp) или как строка UTF-8 (другие формы). В последнем случае используемый код символа — это первый в буфере кодов символов, закодированных в UTF-8, определяемый аргументами p .. e - 1.

toTITLE и toTITLE_A являются синонимами друг друга. Они возвращают заглавную форму символа любого символа ASCII-диапазона в нижнем регистре. В этом диапазоне заглавная форма идентична верхнему регистру. Все остальные входные данные возвращаются без изменений. Поскольку это макросы, тип входных данных может быть любым целым, а выходные данные будут занимать такое же количество битов, что и входные.

Нет toTITLE_L1 и toTITLE_LATIN1, так как заглавная форма некоторых символов в диапазоне 0..255 находится за пределами этого диапазона или состоит из нескольких символов. Используйте вместо этого toTITLE_uvchr.

toTITLE_uvchr возвращает заглавную форму любого символа Юникода. Возвращаемое значение идентично значению toTITLE_A для входных символов в диапазоне ASCII. Заглавная форма подавляющего большинства символов Юникода совпадает с самим символом. Для таких символов и символов, которые находятся за пределами допустимого максимального значения Юникода, эта функция возвращает входной символ без изменений. Кроме того, она сохраняет UTF-8 результата в буфер, начинающийся с s, а его длину в байтах в *lenp. Вызывающая функция должна сделать s достаточно большим, чтобы содержать не менее UTF8_MAXBYTES_CASE+1 байт, чтобы избежать возможного переполнения.

ПРИМЕЧАНИЕ: заглавная форма символа может содержать более одного символа. Возвращаемое значение этой функции — только первый из них. Весь заглавный символ возвращается в s. Чтобы определить, состоит ли результат из более чем одного символа, можно сделать следующее:

uc = toTITLE_uvchr(cp, s, &len);
if (len > UTF8SKIP(s)) { is multiple code points }
else { is a single code point }

toTITLE_utf8 и toTITLE_utf8_safe являются синонимами друг друга. Единственное различие между этими функциями и toTITLE_uvchr заключается в том, что исходный код этих функций закодирован в UTF-8, а не представляет собой код символа. Он передаётся как буфер, начинающийся с p, причём e указывает на байт за концом буфера. Буфер p может содержать более одного символа; но исследуется только первый (до e - 1). Если UTF-8 входного символа некорректен каким-либо образом, программа может прерваться, или функция может вернуть ЗАМЕЩАЮЩИЙ СИМВОЛ по усмотрению реализации и с возможными изменениями в будущих выпусках.

UV  toTITLE          (UV cp)
UV  toTITLE_A        (UV cp)
UV  toTITLE_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toTITLE_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toTITLE_uvchr    (UV cp, U8* s, STRLEN* lenp)
toUPPER
toUPPER_A
toUPPER_utf8
toUPPER_utf8_safe
toUPPER_uvchr

Все эти функции возвращают заглавную букву символа. Различия заключаются в области их применения и в том, задаётся ли входной параметр как код символа (функции с параметром cp) или как строка UTF-8 (другие функции). В последнем случае, используемый код символа — это первый символ в буфере UTF-8 кодированных кодов, ограниченный аргументами p .. e - 1.

toUPPER и toUPPER_A являются синонимами. Они возвращают заглавную букву любого символа в ASCII-диапазоне. Все остальные входные данные возвращаются без изменений. Поскольку это макросы, тип входных данных может быть любым целочисленным, а выходные данные будут занимать такое же количество битов, что и входные.

Нет toUPPER_L1 и toUPPER_LATIN1, так как заглавная буква некоторых символов в диапазоне 0..255 находится за пределами этого диапазона или состоит из нескольких символов. Вместо этого используйте toUPPER_uvchr.

toUPPER_uvchr возвращает заглавную букву любого Unicode-символа. Результат идентичен результату toUPPER_A для входных символов в ASCII-диапазоне. Заглавная буква большинства Unicode-символов совпадает с самим символом. В этих случаях, и для символов, превышающих допустимый максимальный Unicode, функция возвращает входной символ без изменений. Кроме того, она сохраняет UTF-8 результат в буфер, начиная с s, и его длину в байтах в *lenp. Вызывающая функция должна выделить достаточно памяти (s), чтобы вместить не менее UTF8_MAXBYTES_CASE+1 байт, чтобы избежать возможного переполнения.

ПРИМЕЧАНИЕ: заглавная буква символа может состоять из более чем одного символа. Функция возвращает только первый из них. Весь заглавный вариант возвращается в s. Чтобы определить, состоит ли результат более чем из одного символа, можно сделать следующее:

uc = toUPPER_uvchr(cp, s, &len);
if (len > UTF8SKIP(s)) { is multiple code points }
else { is a single code point }

toUPPER_utf8 и toUPPER_utf8_safe являются синонимами друг друга. Единственное отличие этих функций от toUPPER_uvchr заключается в том, что источник для них кодируется в UTF-8, а не является кодом символа. Он передаётся как буфер, начиная с p, а e указывает на один байт за концом буфера. Буфер p может содержать более одного символа; но рассматривается только первый (до e - 1). Если UTF-8 представление входного символа некорректно, программа может завершиться аварийно, либо функция может вернуть ЗАМЕЩАЮЩИЙ СИМВОЛ по усмотрению реализации и с возможностью изменения в будущих версиях.

UV  toUPPER          (UV cp)
UV  toUPPER_A        (UV cp)
UV  toUPPER_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toUPPER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toUPPER_uvchr    (UV cp, U8* s, STRLEN* lenp)

Классификация символов

В этом разделе рассматриваются функции (на самом деле макросы), которые классифицируют символы по типам, таким как знаки препинания против букв и т. д. Большинство из них аналогичны стандартным классам символов в регулярных выражениях. (См. "POSIX Character Classes" в perlrecharclass.) Для каждого класса существуют несколько вариантов. (Не все макросы имеют все варианты; в каждом элементе ниже перечислены имеющиеся варианты.) Ни один из них не зависит от use bytes, и только те, в названии которых есть LC, зависят от текущего языка.

Базовая функция, например, isALPHA(), принимает любое знаковое или беззнаковое значение, рассматривая его как код символа, и возвращает булево значение, указывающее, является ли представляемый им символ (или, на платформах, отличных от ASCII, соответствующий ему символ) ASCII-символом в указанном классе, основываясь на платформе, Unicode и правилах Perl. Если входное число не помещается в один байт, возвращается FALSE.

Вариант isFOO_A (например, isALPHA_A()) идентичен базовой функции без суффикса "_A". Этот вариант используется для подчеркивания в названии, что только символы в ASCII-диапазоне могут вернуть TRUE.

Вариант isFOO_L1 накладывает на платформу набор символов Latin-1 (или эквивалент EBCDIC). То есть символы ASCII не изменяются, поскольку ASCII является подмножеством Latin-1. Но символы, не являющиеся ASCII, обрабатываются так, как если бы они были символами Latin-1. Например, isWORDCHAR_L1() вернёт true, если вызван с кодом символа 0xDF, который является символом слова как в ASCII, так и в EBCDIC (хотя он представляет разные символы в каждом случае). Если входное число не помещается в один байт, возвращается FALSE. (В документации Perl используется разговорное определение Latin-1, которое включает все символы с кодами меньше 256.)

Вариант isFOO_uvchr точно такой же, как и вариант isFOO_L1, для входных данных меньше 256, но если код символа больше 255, используются правила Unicode для определения, находится ли он в указанном классе символов. Например, isWORDCHAR_uvchr(0x100) возвращает TRUE, поскольку 0x100 — это ЗАГЛАВНАЯ ЛАТИНСКАЯ БУКВА A С ДИАРЕЗИСОМ в Unicode и является символом слова.

Варианты isFOO_utf8 и isFOO_utf8_safe подобны isFOO_uvchr, но предназначены для строк UTF-8. Обе формы — разные названия для одного и того же. Каждый вызов одной из них классифицирует первый символ строки, начиная с p. Второй параметр, e, указывает на любую точку в строке после первого символа, до одного байта за концом всей строки. Хотя оба варианта идентичны, суффикс _safe в одном из имён подчёркивает, что он не будет пытаться читать за пределами e - 1, при условии, что ограничение s < e выполняется (это подтверждено в сборках -DDEBUGGING). Если UTF-8 представление входного символа некорректно, программа может завершиться аварийно, или функция может вернуть FALSE по усмотрению реализации, и это может измениться в будущих версиях.

Вариант isFOO_LC похож на варианты isFOO_A и isFOO_L1, но результат зависит от текущего языка, что и подразумевает LC в названии. Если Perl может определить, что текущий язык — UTF-8, он использует опубликованные правила Unicode; в противном случае он использует функцию C-библиотеки, которая даёт указанную классификацию. Например, isDIGIT_LC(), если язык не UTF-8, возвращает результат вызова isdigit(). FALSE всегда возвращается, если входное значение не умещается в один байт. На некоторых платформах, где функция C-библиотеки известна как некорректная, Perl изменяет свой результат, чтобы соответствовать правилам стандарта POSIX.

Вариант isFOO_LC_uvchr действует точно так же, как isFOO_LC для входных значений меньше 256, но для больших значений он возвращает Unicode-классификацию кода символа.

Варианты isFOO_LC_utf8 и isFOO_LC_utf8_safe похожи на isFOO_LC_uvchr, но предназначены для строк UTF-8. Обе формы — разные названия для одного и того же. Каждый вызов одной из них классифицирует первый символ строки, начиная с p. Второй параметр, e, указывает на любую точку в строке после первого символа, до одного байта за концом всей строки. Хотя оба варианта идентичны, суффикс _safe в одном из имён подчёркивает, что он не будет пытаться читать за пределами e - 1, при условии, что ограничение s < e выполняется (это подтверждено в сборках -DDEBUGGING). Если UTF-8 представление входного символа некорректно, программа может завершиться аварийно, или функция может вернуть FALSE по усмотрению реализации, и это может измениться в будущих версиях.

isALNUM
isALNUM_A
isALNUM_LC
isALNUM_LC_uvchr

Эти макросы являются синонимами соответствующего варианта "isWORDCHAR".

Они предоставлены для обратной совместимости, даже если символ слова включает больше, чем стандартное значение алфавитно-цифрового символа в языке C. Чтобы получить определение языка C, используйте соответствующий вариант "isALPHANUMERIC".

bool  isALNUM(UV ch)
isALNUMC
isALNUMC_A
isALNUMC_LC
isALNUMC_LC_uvchr
isALNUMC_L1

Эти макросы не рекомендуются, это макросы обратной совместимости для "isALPHANUMERIC". То есть каждый из них возвращает булево значение, указывающее, является ли указанный символ одним из [A-Za-z0-9], аналогично m/[[:alnum:]]/.

Суффикс C в именах должен был указывать, что они соответствуют функции C isalnum(3).

bool  isALNUMC(UV ch)
isALPHA
isALPHA_A
isALPHA_LC
isALPHA_LC_utf8_safe
isALPHA_LC_uvchr
isALPHA_L1
isALPHA_utf8
isALPHA_utf8_safe
isALPHA_uvchr

Возвращает булево значение, указывающее, является ли указанный входной параметр одним из [A-Za-z], аналогично m/[[:alpha:]]/. См. начало этого раздела Классификация символов для объяснения вариантов.

bool  isALPHA             (UV ch)
bool  isALPHA_A           (UV ch)
bool  isALPHA_LC          (UV ch)
bool  isALPHA_LC_utf8_safe(U8 * s, U8 *end)
bool  isALPHA_LC_uvchr    (UV ch)
bool  isALPHA_L1          (UV ch)
bool  isALPHA_utf8        (U8 * s, U8 * end)
bool  isALPHA_utf8_safe   (U8 * s, U8 * end)
bool  isALPHA_uvchr       (UV ch)
isALPHANUMERIC
isALPHANUMERIC_A
isALPHANUMERIC_LC
isALPHANUMERIC_LC_utf8_safe
isALPHANUMERIC_LC_uvchr
isALPHANUMERIC_L1
isALPHANUMERIC_utf8
isALPHANUMERIC_utf8_safe
isALPHANUMERIC_uvchr

Возвращает булево значение, указывающее, является ли указанный символ одним из [A-Za-z0-9], аналогично m/[[:alnum:]]/. См. начало этого раздела Классификация символов для объяснения вариантов.

bool  isALPHANUMERIC             (UV ch)
bool  isALPHANUMERIC_A           (UV ch)
bool  isALPHANUMERIC_LC          (UV ch)
bool  isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end)
bool  isALPHANUMERIC_LC_uvchr    (UV ch)
bool  isALPHANUMERIC_L1          (UV ch)
bool  isALPHANUMERIC_utf8        (U8 * s, U8 * end)
bool  isALPHANUMERIC_utf8_safe   (U8 * s, U8 * end)
bool  isALPHANUMERIC_uvchr       (UV ch)
isASCII
isASCII_A
isASCII_LC
isASCII_LC_utf8_safe
isASCII_LC_uvchr
isASCII_L1
isASCII_utf8
isASCII_utf8_safe
isASCII_uvchr

Возвращает булево значение, указывающее, является ли указанный символ одним из 128 символов набора символов ASCII, аналогично m/[[:ascii:]]/. В платформах, отличных от ASCII, она возвращает ИСТИНА тогда и только тогда, когда этот символ соответствует символу ASCII. Варианты isASCII_A() и isASCII_L1() идентичны isASCII(). См. начало этого раздела для объяснения вариантов. Обратите, однако, внимание, что некоторые платформы не имеют функцию C-библиотеки isascii(). В таких случаях, варианты, имена которых содержат LC, эквивалентны соответствующим без них.

Также обратите внимание, что поскольку все символы ASCII являются инвариантными для UTF-8 (то есть, они имеют то же самое представление (всегда один байт), независимо от того, закодированы ли они в UTF-8 или нет), isASCII даст правильные результаты при вызове с любым байтом в любой строке, закодированной или нет в UTF-8. И аналогично isASCII_utf8 и isASCII_utf8_safe будут работать корректно с любой строкой, закодированной или нет в UTF-8.

bool  isASCII             (UV ch)
bool  isASCII_A           (UV ch)
bool  isASCII_LC          (UV ch)
bool  isASCII_LC_utf8_safe(U8 * s, U8 *end)
bool  isASCII_LC_uvchr    (UV ch)
bool  isASCII_L1          (UV ch)
bool  isASCII_utf8        (U8 * s, U8 * end)
bool  isASCII_utf8_safe   (U8 * s, U8 * end)
bool  isASCII_uvchr       (UV ch)
isBLANK
isBLANK_A
isBLANK_LC
isBLANK_LC_utf8_safe
isBLANK_LC_uvchr
isBLANK_L1
isBLANK_utf8
isBLANK_utf8_safe
isBLANK_uvchr

Возвращает булево значение, указывающее, является ли указанный символ символом, который считается пробелом, аналогично m/[[:blank:]]/. См. начало этого раздела для объяснения вариантов. Обратите, однако, внимание, что некоторые платформы не имеют функцию C-библиотеки isblank(). В таких случаях, варианты, имена которых содержат LC, эквивалентны соответствующим без них.

bool  isBLANK             (UV ch)
bool  isBLANK_A           (UV ch)
bool  isBLANK_LC          (UV ch)
bool  isBLANK_LC_utf8_safe(U8 * s, U8 *end)
bool  isBLANK_LC_uvchr    (UV ch)
bool  isBLANK_L1          (UV ch)
bool  isBLANK_utf8        (U8 * s, U8 * end)
bool  isBLANK_utf8_safe   (U8 * s, U8 * end)
bool  isBLANK_uvchr       (UV ch)
isCNTRL
isCNTRL_A
isCNTRL_LC
isCNTRL_LC_utf8_safe
isCNTRL_LC_uvchr
isCNTRL_L1
isCNTRL_utf8
isCNTRL_utf8_safe
isCNTRL_uvchr

Возвращает булево значение, указывающее, является ли указанный символ управляющим символом, аналогично m/[[:cntrl:]]/. См. начало этого раздела для объяснения вариантов. В платформах EBCDIC, вы почти всегда должны использовать вариант isCNTRL_L1. 

bool  isCNTRL             (UV ch)
bool  isCNTRL_A           (UV ch)
bool  isCNTRL_LC          (UV ch)
bool  isCNTRL_LC_utf8_safe(U8 * s, U8 *end)
bool  isCNTRL_LC_uvchr    (UV ch)
bool  isCNTRL_L1          (UV ch)
bool  isCNTRL_utf8        (U8 * s, U8 * end)
bool  isCNTRL_utf8_safe   (U8 * s, U8 * end)
bool  isCNTRL_uvchr       (UV ch)
isDIGIT
isDIGIT_A
isDIGIT_LC
isDIGIT_LC_utf8_safe
isDIGIT_LC_uvchr
isDIGIT_L1
isDIGIT_utf8
isDIGIT_utf8_safe
isDIGIT_uvchr

Возвращает булево значение, указывающее, является ли указанный символ цифрой, аналогично m/[[:digit:]]/. Варианты isDIGIT_A и isDIGIT_L1 идентичны isDIGIT. См. начало этого раздела для объяснения вариантов.

bool  isDIGIT             (UV ch)
bool  isDIGIT_A           (UV ch)
bool  isDIGIT_LC          (UV ch)
bool  isDIGIT_LC_utf8_safe(U8 * s, U8 *end)
bool  isDIGIT_LC_uvchr    (UV ch)
bool  isDIGIT_L1          (UV ch)
bool  isDIGIT_utf8        (U8 * s, U8 * end)
bool  isDIGIT_utf8_safe   (U8 * s, U8 * end)
bool  isDIGIT_uvchr       (UV ch)
isGRAPH
isGRAPH_A
isGRAPH_LC
isGRAPH_LC_utf8_safe
isGRAPH_LC_uvchr
isGRAPH_L1
isGRAPH_utf8
isGRAPH_utf8_safe
isGRAPH_uvchr

Возвращает булево значение, указывающее, является ли указанный символ графическим символом, аналогично m/[[:graph:]]/. См. начало этого раздела для объяснения вариантов.

bool  isGRAPH             (UV ch)
bool  isGRAPH_A           (UV ch)
bool  isGRAPH_LC          (UV ch)
bool  isGRAPH_LC_utf8_safe(U8 * s, U8 *end)
bool  isGRAPH_LC_uvchr    (UV ch)
bool  isGRAPH_L1          (UV ch)
bool  isGRAPH_utf8        (U8 * s, U8 * end)
bool  isGRAPH_utf8_safe   (U8 * s, U8 * end)
bool  isGRAPH_uvchr       (UV ch)
isIDCONT
isIDCONT_A
isIDCONT_LC
isIDCONT_LC_utf8_safe
isIDCONT_LC_uvchr
isIDCONT_L1
isIDCONT_utf8
isIDCONT_utf8_safe
isIDCONT_uvchr

Возвращает булево значение, указывающее, может ли указанный символ быть вторым или последующим символом идентификатора. Это очень близко к, но не совсем то же самое, что официальное свойство Unicode XID_Continue. Разница заключается в том, что это возвращает true только в том случае, если входной символ также соответствует "isWORDCHAR". См. начало этого раздела для объяснения вариантов.

bool  isIDCONT             (UV ch)
bool  isIDCONT_A           (UV ch)
bool  isIDCONT_LC          (UV ch)
bool  isIDCONT_LC_utf8_safe(U8 * s, U8 *end)
bool  isIDCONT_LC_uvchr    (UV ch)
bool  isIDCONT_L1          (UV ch)
bool  isIDCONT_utf8        (U8 * s, U8 * end)
bool  isIDCONT_utf8_safe   (U8 * s, U8 * end)
bool  isIDCONT_uvchr       (UV ch)
isIDFIRST
isIDFIRST_A
isIDFIRST_LC
isIDFIRST_LC_utf8_safe
isIDFIRST_LC_uvchr
isIDFIRST_L1
isIDFIRST_utf8
isIDFIRST_utf8_safe
isIDFIRST_uvchr

Возвращает булево значение, указывающее, может ли указанный символ быть первым символом идентификатора. Это очень близко к, но не совсем то же самое, что официальное свойство Unicode XID_Start. Разница заключается в том, что это возвращает true только в том случае, если входной символ также соответствует "isWORDCHAR". См. начало этого раздела для объяснения вариантов.

bool  isIDFIRST             (UV ch)
bool  isIDFIRST_A           (UV ch)
bool  isIDFIRST_LC          (UV ch)
bool  isIDFIRST_LC_utf8_safe(U8 * s, U8 *end)
bool  isIDFIRST_LC_uvchr    (UV ch)
bool  isIDFIRST_L1          (UV ch)
bool  isIDFIRST_utf8        (U8 * s, U8 * end)
bool  isIDFIRST_utf8_safe   (U8 * s, U8 * end)
bool  isIDFIRST_uvchr       (UV ch)
isLOWER
isLOWER_A
isLOWER_LC
isLOWER_LC_utf8_safe
isLOWER_LC_uvchr
isLOWER_L1
isLOWER_utf8
isLOWER_utf8_safe
isLOWER_uvchr

Возвращает булево значение, указывающее, является ли указанный символ строчным символом, аналогично m/[[:lower:]]/. См. начало этого раздела для объяснения вариантов.

bool  isLOWER             (UV ch)
bool  isLOWER_A           (UV ch)
bool  isLOWER_LC          (UV ch)
bool  isLOWER_LC_utf8_safe(U8 * s, U8 *end)
bool  isLOWER_LC_uvchr    (UV ch)
bool  isLOWER_L1          (UV ch)
bool  isLOWER_utf8        (U8 * s, U8 * end)
bool  isLOWER_utf8_safe   (U8 * s, U8 * end)
bool  isLOWER_uvchr       (UV ch)
isOCTAL
isOCTAL_A
isOCTAL_L1

Возвращает булево значение, указывающее, является ли указанный символ восьмеричной цифрой, [0-7]. Единственные два варианта - isOCTAL_A и isOCTAL_L1; каждый идентичен isOCTAL.

bool  isOCTAL(UV ch)
isPRINT
isPRINT_A
isPRINT_LC
isPRINT_LC_utf8_safe
isPRINT_LC_uvchr
isPRINT_L1
isPRINT_utf8
isPRINT_utf8_safe
isPRINT_uvchr

Возвращает булево значение, указывающее, является ли указанный символ печатным символом, аналогично m/[[:print:]]/. См. начало этого раздела для объяснения вариантов.

bool  isPRINT             (UV ch)
bool  isPRINT_A           (UV ch)
bool  isPRINT_LC          (UV ch)
bool  isPRINT_LC_utf8_safe(U8 * s, U8 *end)
bool  isPRINT_LC_uvchr    (UV ch)
bool  isPRINT_L1          (UV ch)
bool  isPRINT_utf8        (U8 * s, U8 * end)
bool  isPRINT_utf8_safe   (U8 * s, U8 * end)
bool  isPRINT_uvchr       (UV ch)
isPSXSPC
isPSXSPC_A
isPSXSPC_LC
isPSXSPC_LC_utf8_safe
isPSXSPC_LC_uvchr
isPSXSPC_L1
isPSXSPC_utf8
isPSXSPC_utf8_safe
isPSXSPC_uvchr

(сокращенно Posix Space) Начиная с версии 5.18, этот вариант во всех своих формах идентичен соответствующим isSPACE() макросам. Локализованные формы этого макроса идентичны соответствующим isSPACE() формам во всех выпусках Perl. В выпусках до 5.18, нелокализованные формы отличаются от isSPACE() форм только тем, что isSPACE() формы не соответствуют вертикальной табуляции, а isPSXSPC() формы соответствуют. В противном случае они идентичны. Таким образом, этот макрос аналогичен тому, что m/[[:space:]]/ соответствует в регулярном выражении. См. начало этого раздела для объяснения вариантов.

bool  isPSXSPC             (UV ch)
bool  isPSXSPC_A           (UV ch)
bool  isPSXSPC_LC          (UV ch)
bool  isPSXSPC_LC_utf8_safe(U8 * s, U8 *end)
bool  isPSXSPC_LC_uvchr    (UV ch)
bool  isPSXSPC_L1          (UV ch)
bool  isPSXSPC_utf8        (U8 * s, U8 * end)
bool  isPSXSPC_utf8_safe   (U8 * s, U8 * end)
bool  isPSXSPC_uvchr       (UV ch)
isPUNCT
isPUNCT_A
isPUNCT_LC
isPUNCT_LC_utf8_safe
isPUNCT_LC_uvchr
isPUNCT_L1
isPUNCT_utf8
isPUNCT_utf8_safe
isPUNCT_uvchr

Возвращает булево значение, указывающее, является ли указанный символ символом пунктуации, аналогично m/[[:punct:]]/. Обратите внимание, что определение того, что является пунктуацией, не является таким простым, как можно было бы ожидать. См. "POSIX Character Classes" в perlrecharclass для получения подробностей. См. начало этого раздела для объяснения вариантов.

bool  isPUNCT             (UV ch)
bool  isPUNCT_A           (UV ch)
bool  isPUNCT_LC          (UV ch)
bool  isPUNCT_LC_utf8_safe(U8 * s, U8 *end)
bool  isPUNCT_LC_uvchr    (UV ch)
bool  isPUNCT_L1          (UV ch)
bool  isPUNCT_utf8        (U8 * s, U8 * end)
bool  isPUNCT_utf8_safe   (U8 * s, U8 * end)
bool  isPUNCT_uvchr       (UV ch)
isSPACE
isSPACE_A
isSPACE_LC
isSPACE_LC_utf8_safe
isSPACE_LC_uvchr
isSPACE_L1
isSPACE_utf8
isSPACE_utf8_safe
isSPACE_uvchr

Возвращает булево значение, указывающее, является ли указанный символ символом пробела. Это аналогично тому, что m/\s/ соответствует в регулярном выражении. Начиная с Perl 5.18, это также соответствует тому, что m/[[:space:]]/ делает. До версии 5.18 только локализованные формы этого макроса (те, в которых LC присутствует в их именах) точно соответствовали тому, что m/[[:space:]]/ делает. В этих выпусках единственное отличие в нелокализованных вариантах заключалось в том, что isSPACE() не соответствовал вертикальной табуляции. (См. "isPSXSPC" для макроса, который соответствует вертикальной табуляции во всех выпусках.) См. начало этого раздела для объяснения вариантов.

bool  isSPACE             (UV ch)
bool  isSPACE_A           (UV ch)
bool  isSPACE_LC          (UV ch)
bool  isSPACE_LC_utf8_safe(U8 * s, U8 *end)
bool  isSPACE_LC_uvchr    (UV ch)
bool  isSPACE_L1          (UV ch)
bool  isSPACE_utf8        (U8 * s, U8 * end)
bool  isSPACE_utf8_safe   (U8 * s, U8 * end)
bool  isSPACE_uvchr       (UV ch)
isUPPER
isUPPER_A
isUPPER_LC
isUPPER_LC_utf8_safe
isUPPER_LC_uvchr
isUPPER_L1
isUPPER_utf8
isUPPER_utf8_safe
isUPPER_uvchr

Возвращает булево значение, указывающее, является ли указанный символ заглавным, аналогично m/[[:upper:]]/. Смотрите начало этого раздела вверху для объяснения вариантов.

bool  isUPPER             (UV ch)
bool  isUPPER_A           (UV ch)
bool  isUPPER_LC          (UV ch)
bool  isUPPER_LC_utf8_safe(U8 * s, U8 *end)
bool  isUPPER_LC_uvchr    (UV ch)
bool  isUPPER_L1          (UV ch)
bool  isUPPER_utf8        (U8 * s, U8 * end)
bool  isUPPER_utf8_safe   (U8 * s, U8 * end)
bool  isUPPER_uvchr       (UV ch)
isWORDCHAR
isWORDCHAR_A
isWORDCHAR_LC
isWORDCHAR_LC_utf8_safe
isWORDCHAR_LC_uvchr
isWORDCHAR_L1
isWORDCHAR_utf8
isWORDCHAR_utf8_safe
isWORDCHAR_uvchr

Возвращает булево значение, указывающее, является ли указанный символ символом, который является символом слова, аналогично тому, что m/\w/ и m/[[:word:]]/ соответствуют в регулярном выражении. Символ слова — это буквенный символ, десятичная цифра, символ пунктуации соединения (например, нижнее подчеркивание) или символ «метки», который прикрепляется к одному из них (например, некоторые типы акцентов).

Смотрите начало этого раздела вверху для объяснения вариантов.

isWORDCHAR_A, isWORDCHAR_L1, isWORDCHAR_uvchr, isWORDCHAR_LC, isWORDCHAR_LC_uvchr, isWORDCHAR_LC_utf8, и isWORDCHAR_LC_utf8_safe также описаны там, но дополнительно включают системное нижнее подчеркивание.

bool  isWORDCHAR             (UV ch)
bool  isWORDCHAR_A           (UV ch)
bool  isWORDCHAR_LC          (UV ch)
bool  isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end)
bool  isWORDCHAR_LC_uvchr    (UV ch)
bool  isWORDCHAR_L1          (UV ch)
bool  isWORDCHAR_utf8        (U8 * s, U8 * end)
bool  isWORDCHAR_utf8_safe   (U8 * s, U8 * end)
bool  isWORDCHAR_uvchr       (UV ch)
isXDIGIT
isXDIGIT_A
isXDIGIT_LC
isXDIGIT_LC_utf8_safe
isXDIGIT_LC_uvchr
isXDIGIT_L1
isXDIGIT_utf8
isXDIGIT_utf8_safe
isXDIGIT_uvchr

Возвращает булево значение, указывающее, является ли указанный символ шестнадцатеричной цифрой. В диапазоне ASCII это [0-9A-Fa-f]. Варианты isXDIGIT_A() и isXDIGIT_L1() идентичны isXDIGIT(). Смотрите начало этого раздела вверху для объяснения вариантов.

bool  isXDIGIT             (UV ch)
bool  isXDIGIT_A           (UV ch)
bool  isXDIGIT_LC          (UV ch)
bool  isXDIGIT_LC_utf8_safe(U8 * s, U8 *end)
bool  isXDIGIT_LC_uvchr    (UV ch)
bool  isXDIGIT_L1          (UV ch)
bool  isXDIGIT_utf8        (U8 * s, U8 * end)
bool  isXDIGIT_utf8_safe   (U8 * s, U8 * end)
bool  isXDIGIT_uvchr       (UV ch)

Сведения о компиляторе и препроцессоре

CPPLAST

Этот символ предназначен для использования вместе с CPPRUN таким же образом, как символ CPPMINUS используется с CPPSTDIN. Он содержит либо «-», либо «».

CPPMINUS

Этот символ содержит вторую часть строки, которая вызовет C препроцессор на стандартном вводе и выведет на стандартный вывод. Этот символ будет иметь значение «-», если CPPSTDIN требует минуса для указания стандартного ввода, в противном случае значение равно «».

CPPRUN

Этот символ содержит строку, которая вызовет C препроцессор на стандартном вводе и выведет на стандартный вывод. Она должна заканчиваться CPPLAST, после указания всех остальных флагов препроцессора. Основное различие с CPPSTDIN заключается в том, что эта программа никогда не будет указателем на оболочку, т. е. она будет пустой, если препроцессор недоступен пользователю напрямую. Обратите внимание, что она может сильно отличаться от препроцессора, используемого для компиляции C программы.

CPPSTDIN

Этот символ содержит первую часть строки, которая вызовет C препроцессор на стандартном вводе и выведет на стандартный вывод. Типичное значение «cc -E» или «/lib/cpp», но также может вызвать оболочку. Смотрите "CPPRUN".

HASATTRIBUTE_ALWAYS_INLINE

Можно ли обработать атрибут GCC для функций, которые должны всегда быть встроены.

HASATTRIBUTE_DEPRECATED

Можно ли обработать атрибут GCC для маркировки устаревших APIs

HASATTRIBUTE_FORMAT

Можно ли обработать атрибут GCC для проверки форматов в стиле printf

HASATTRIBUTE_NONNULL

Можно ли обработать атрибут GCC для параметров функций, которые не должны быть нулевыми.

HASATTRIBUTE_NORETURN

Можно ли обработать атрибут GCC для функций, которые не возвращают значение

HASATTRIBUTE_PURE

Можно ли обработать атрибут GCC для чистых функций

HASATTRIBUTE_UNUSED

Можно ли обработать атрибут GCC для неиспользуемых переменных и аргументов

HASATTRIBUTE_VISIBILITY

Можно ли обработать атрибут GCC для функций, которые должны иметь другую видимость.

HASATTRIBUTE_WARN_UNUSED_RESULT

Можно ли обработать атрибут GCC для выдачи предупреждения о неиспользуемых результатах

HAS_BUILTIN_ADD_OVERFLOW

Если этот символ определён, это указывает, что компилятор поддерживает __builtin_add_overflow для сложения целых чисел с проверкой переполнения.

HAS_BUILTIN_CHOOSE_EXPR

Можно ли обработать встроенную функцию GCC для выражений с условным оператором на этапе компиляции

HAS_BUILTIN_EXPECT

Можно ли обработать встроенную функцию GCC для указания большей вероятности определённых значений

HAS_BUILTIN_MUL_OVERFLOW

Если этот символ определён, это указывает, что компилятор поддерживает __builtin_mul_overflow для умножения целых чисел с проверкой переполнения.

HAS_BUILTIN_SUB_OVERFLOW

Если этот символ определён, это указывает, что компилятор поддерживает __builtin_sub_overflow для вычитания целых чисел с проверкой переполнения.

HAS_C99_VARIADIC_MACROS

Если определён, компилятор поддерживает макросы C99 с переменным числом аргументов.

HAS_STATIC_INLINE

Если этот символ определён, это указывает, что C компилятор поддерживает статические inline функции в стиле C99. То есть, функцию нельзя вызвать из другого блока трансляции.

MEM_ALIGNBYTES

Этот символ содержит количество байтов, необходимое для выравнивания double, или long double, если применимо. Обычные значения 2, 4 и 8. По умолчанию восемь, для безопасности. При кросс-компиляции или поддержке нескольких архитектур Configure установит минимум 8.

PERL_STATIC_INLINE

Этот символ даёт наилучшую оценку для использования статических inline функций. Если HAS_STATIC_INLINE определён, это даст inline функции в стиле C99. Если HAS_STATIC_INLINE не определён, это даст обычное 'static'. Он всегда будет определён как что-то, что даёт статическую ссылку. Возможные варианты включают

static inline       (c99)
static __inline__   (gcc -ansi)
static __inline     (MSVC)
static _inline      (older MSVC)
static              (c89 compilers)
PERL_THREAD_LOCAL

Если этот символ определён, он даёт спецификацию ссылки для хранения данных в рамках потока. Например, для C11 компилятора это будет _Thread_local. Следует быть осторожным, некоторые компиляторы чувствительны к стандарту языка C, который они получают для анализа. Например, suncc по умолчанию использует C11, поэтому наш зонд сообщит, что _Thread_local может быть использован. Однако, если позже будет добавлен флаг -std=c99 в флаги компилятора, то _Thread_local станет синтаксической ошибкой. Поэтому важно, чтобы эти флаги были согласованы между зондированием и использованием.

U32_ALIGNMENT_REQUIRED

Если этот символ определён, это указывает, что вы должны обращаться к данным символов через указатели, выровненные по U32.

Директивы компилятора

__ASSERT_

Это вспомогательный макрос для предотвращения проблем с препроцессором, заменяется пустым значением, если не включено отладка. В противном случае он расширяется до проверки аргумента, за которым следует запятая (отсюда оператор запятой). Если мы просто использовали assert(), мы бы получили запятую без значения перед ней, если не включена отладка.

__ASSERT_(bool expr)
ASSUME

ASSUME похож на assert(), но имеет преимущество в релизной сборке. Это подсказка для компилятора о факте в вызове функции свободного выражения, что позволяет компилятору генерировать более эффективный машинный код. В отладочной сборке ASSUME(x) является синонимом assert(x). ASSUME(0) означает, что путь управления недостижим. В цикле for ASSUME можно использовать для указания, что цикл будет выполняться не менее X раз. ASSUME основан на встроенной функции __assume MSVC, см. документацию для более подробной информации.

ASSUME(bool expr)
dNOOP

Не объявлять ничего; обычно используется как заполнитель для замены того, что использовалось для объявления чего-либо. Работает с компиляторами, которые требуют объявлений перед любым кодом.

dNOOP;
END_EXTERN_C

При компиляции без C++, расширяется до ничего. В противном случае завершает раздел кода, уже начатый "START_EXTERN_C".

END_EXTERN_C
EXTERN_C

При компиляции без C++, расширяется до ничего. В противном случае используется в объявлении функции для указания, что функция должна иметь внешнюю C-связь. Это необходимо для работы практически всех функций с внешней ссылкой, скомпилированных в perl. Часто вы можете использовать "START_EXTERN_C" ... "END_EXTERN_C" блоки, окружающие весь код, который вам нужно иметь эту ссылку.

Пример использования:

EXTERN_C int flock(int fd, int op);
LIKELY

Возвращает входное значение без изменений, но в то же время даёт компилятору подсказку о прогнозировании ветвления, что это условие, скорее всего, истинно.

LIKELY(bool expr)
NOOP

Ничего не делать; обычно используется как заполнитель для замены того, что использовалось для выполнения чего-либо.

NOOP;
PERL_UNUSED_ARG

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

PERL_UNUSED_ARG(void x);
PERL_UNUSED_CONTEXT

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

PERL_UNUSED_CONTEXT;
PERL_UNUSED_DECL

Сообщает компилятору, что параметр в прототипе функции, непосредственно перед ним, не обязательно должен использоваться в функции. Не так много компиляторов понимают это, поэтому это следует использовать только в тех случаях, где "PERL_UNUSED_ARG" не может быть удобно использовано.

Пример использования:

Signal_t
Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
                      void *uap PERL_UNUSED_DECL, bool safe)
PERL_UNUSED_RESULT

Эта макрос указывает на отбрасывание значения возврата вызова функции внутри него, например,

PERL_UNUSED_RESULT(foo(a, b))

Основной причиной этого является то, что сочетание gcc -Wunused-result (часть -Wall) и __attribute__((warn_unused_result)) не может быть подавлено приведением к типу void. Это создаёт проблемы, когда файлы заголовков системы используют этот атрибут.

Однако используйте PERL_UNUSED_RESULT экономно, так как обычно предупреждение существует по какой-то причине: вы можете потерять информацию об успехе/неудаче, утечь ресурсы или изменить ресурсы.

Но иногда вы просто хотите проигнорировать возвращаемое значение, например, на участках кода, которые вскоре завершатся прерыванием, или в попытках «лучшего решения», или в ситуациях, когда нет хорошего способа обработать ошибки.

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

PERL_UNUSED_RESULT(void x)
PERL_UNUSED_VAR

Это используется для подавления предупреждений компилятора о том, что переменная x не используется. Такая ситуация может возникнуть, например, когда условное компилирование с помощью препроцессора C приводит к тому, что она используется только в некоторых случаях.

PERL_UNUSED_VAR(void x);
START_EXTERN_C

При компиляции без использования C++, расширяется до ничего. В противном случае начинается раздел кода, в котором каждая функция будет фактически иметь "EXTERN_C" применённым к ней, то есть иметь внешнюю C-связь. Раздел завершается "END_EXTERN_C". 

START_EXTERN_C
STATIC

Описание в perlguts.

STMT_END
STMT_START

Эти элементы позволяют использовать серию операторов в макросе как один оператор, как в

if (x) STMT_START { ... } STMT_END else ...

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

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

#define foo(param, type)  STMT_START {
                             type * param; *param = do_calc; ...
                          } STMT_END

Это может быть неудобно, поэтому вместо этого рассмотрите возможность использования C-функции static inline.

Если вы используете этот конструкт, легко забыть, что это макрос, а не функция, и, следовательно, попасть в ловушки, которые могут проявиться только когда-нибудь, когда кто-то напишет код, содержащий имена, совпадающие с вашими, или вызовет его с параметром, который является выражением с побочными эффектами, о последствиях которых вы не думали. См. "Writing safer macros" в perlhacktips для того, как избежать этих проблем.

UNLIKELY

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

UNLIKELY(bool expr)

Временные метки области компиляции

BhkDISABLE

ПРИМЕЧАНИЕ: BhkDISABLE является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Временно отключить запись в этой структуре BHK, очистив соответствующий флаг. which — это препроцессорный токен, указывающий, какую запись отключить.

void  BhkDISABLE(BHK *hk, token which)
BhkENABLE

ПРИМЕЧАНИЕ: BhkENABLE является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Включить запись в этой структуре BHK, установив соответствующий флаг. which — это препроцессорный токен, указывающий, какую запись включить. Это вызовет утверждение (при -DDEBUGGING), если запись не содержит действительного указателя.

void  BhkENABLE(BHK *hk, token which)
BhkENTRY_set

ПРИМЕЧАНИЕ: BhkENTRY_set является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Установить запись в структуре BHK и установить флаги, чтобы указать, что она действительна. which — это препроцессорный токен, указывающий, какую запись установить. Тип ptr зависит от записи.

void  BhkENTRY_set(BHK *hk, token which, void *ptr)
blockhook_register

ПРИМЕЧАНИЕ: blockhook_register является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Регистрирует набор хуков, которые будут вызываться при изменении лексической области Perl во время компиляции. См. "Compile-time scope hooks" в perlguts.

ПРИМЕЧАНИЕ: blockhook_register должен быть явно вызван как Perl_blockhook_register с параметром aTHX_. 

void  Perl_blockhook_register(pTHX_ BHK *hk)

Конкурентность

aTHX

Описание в perlguts.

aTHX_

Описание в perlguts.

CPERLscope

DEPRECATED! Планируется удалить CPERLscope из будущих выпусков Perl. Не используйте его в новом коде; удалите его из существующего кода.

Теперь это бесполезная операция.

void  CPERLscope(void x)
dTHR

Описание в perlguts.

dTHX

Описание в perlguts.

dTHXa

В потоковых Perl, установите pTHX на a; в не-потоковых Perl, ничего не делайте

dTHXoa

Теперь синоним для "dTHXa".

dVAR

Теперь это синоним для dNOOP: ничего не объявлять.

GETENV_PRESERVES_OTHER_THREAD

Если этот символ определён, это означает, что системный вызов getenv не удаляет статический буфер getenv() в другом потоке. Типичная реализация getenv() вернёт указатель на правильную позицию в **environ. Но некоторые могут вместо этого скопировать их в статический буфер в getenv(). Если существует экземпляр этого буфера на поток или возвращаемый указатель указывает на **environ, то многопоточный мьютекс «многие читатели/один писатель» будет работать; в противном случае требуется эксклюзивный мьютекс для предотвращения гонок.

HAS_PTHREAD_ATFORK

Если этот символ определён, это указывает, что процедура pthread_atfork доступна для настройки обработчиков fork.

HAS_PTHREAD_ATTR_SETSCOPE

Если этот символ определён, это указывает, что системный вызов pthread_attr_setscope доступен для установки атрибута области конкуренции объекта атрибута потока.

HAS_PTHREAD_YIELD

Если этот символ определён, это указывает, что процедура pthread_yield доступна для уступки выполнения текущего потока. sched_yield предпочтительнее pthread_yield.

HAS_SCHED_YIELD

Если этот символ определён, это указывает, что процедура sched_yield доступна для уступки выполнения текущего потока. sched_yield предпочтительнее pthread_yield.

I_MACH_CTHREADS

Если этот символ определён, это означает, что C-программа должна включить mach/cthreads.h.

#ifdef I_MACH_CTHREADS
    #include <mach_cthreads.h>
#endif
I_PTHREAD

Если этот символ определён, это означает, что C-программа должна включить pthread.h.

#ifdef I_PTHREAD
    #include <pthread.h>
#endif
MULTIPLICITY

Если этот символ определён, это означает, что Perl должен быть скомпилирован с использованием множественности.

OLD_PTHREAD_CREATE_JOINABLE

Если этот символ определён, это указывает, как создать pthread в присоединяемом (т.е. неоткреплённом) состоянии. NOTE: не определён, если pthread.h уже определил PTHREAD_CREATE_JOINABLE (новая версия константы). Если определён, известные значения — PTHREAD_CREATE_UNDETACHED и __UNDETACHED.

OLD_PTHREADS_API

Если этот символ определён, это означает, что Perl должен быть скомпилирован с использованием старого черновика POSIX потоков API.

PERL_IMPLICIT_CONTEXT

Описание в perlguts.

PERL_NO_GET_CONTEXT

Описание в perlguts.

pTHX

Описание в perlguts.

pTHX_

Описание в perlguts.

SCHED_YIELD

Этот символ определяет способ уступки выполнения текущего потока. Известные способы: sched_yield, pthread_yield, и pthread_yield с NULL.

COPы и хэши подсказок

cop_fetch_label

ПРИМЕЧАНИЕ: cop_fetch_label является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Возвращает метку, присоединённую к COPу, и сохраняет её длину в байтах в *len. По возвращении *flags будет установлено либо на SVf_UTF8, либо на 0.

В качестве альтернативы, используйте макрос "CopLABEL_len_flags"; или, если вам не нужно знать, является ли метка UTF-8, используйте макрос "CopLABEL_len"; или, если вам не нужна длина, используйте макрос "CopLABEL".

const char *  cop_fetch_label(COP * const cop, STRLEN *len,
                              U32 *flags)
CopFILE

Возвращает имя файла, связанного с COP c

const char *  CopFILE(const COP * c)
CopFILEAV

Возвращает AV, связанный с COP c, создавая его при необходимости.

AV *  CopFILEAV(const COP * c)
CopFILEAVn

Возвращает AV, связанный с COP c, возвращая NULL, если он ещё не существует.

AV *  CopFILEAVn(const COP * c)
CopFILE_copy

Эффективно копирует имя файла cop из одного COP в другой. Оборачивает необходимую логику для копирования со счетом ссылок в потоках или без них.

void  CopFILE_copy(COP * dst, COP * src)
CopFILE_free

Освобождает данные файла в cop. Под капотом это операция подсчета ссылок.

void  CopFILE_free(COP * c)
CopFILEGV

Возвращает GV, связанный с COP c

GV *  CopFILEGV(const COP * c)
CopFILEGV_set

Доступно только в не-потоковых Perl-ах. Устанавливает pv в качестве имени файла, связанного с COP c

void  CopFILEGV_set(COP *c, GV *gv)
CopFILE_LEN

Возвращает длину файла, связанного с COP c

const char *  CopFILE_LEN(const COP * c)
CopFILE_set

Устанавливает pv в качестве имени файла, связанного с COP c

void  CopFILE_set(COP * c, const char * pv)
CopFILE_setn

Устанавливает pv в качестве имени файла, связанного с COP c

void  CopFILE_setn(COP * c, const char * pv, STRLEN len)
CopFILESV

Возвращает SV, связанный с COP c

SV *  CopFILESV(const COP * c)
cophh_copy

ПРИМЕЧАНИЕ: cophh_copy является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Создаёт и возвращает полную копию хеша подсказок cop cophh.

COPHH *  cophh_copy(COPHH *cophh)
cophh_delete_pv
cophh_delete_pvn
cophh_delete_pvs
cophh_delete_sv

ПРИМЕЧАНИЕ: все эти формы являются экспериментальными и могут быть изменены или удалены без предварительного уведомления.

Удаляют ключ и его связанное значение из хеша подсказок cop cophh, возвращая изменённый хеш. Указатель на возвращённый хеш, как правило, отличается от указателя на переданный хеш. Входной хеш потребляется функцией, и указатель на него не должен использоваться в дальнейшем. Используйте "cophh_copy", если вам нужны оба хеша.

Формы различаются тем, как задаётся ключ. Во всех формах ключ указывается через key. В обычной форме pv, ключ представляет собой C-строку с завершающим нулём. В форме pvs, ключ представляет собой C-строку-литерал. В форме pvn, дополнительный параметр keylen указывает длину строки, которая, следовательно, может содержать вставленные нули. В форме sv, *key является SV, и ключ — это PV, извлечённый из него, используя "SvPV_const".

hash — это предварительно вычисленный хеш строки ключа или ноль, если он не был предварительно вычислен. Этот параметр опущен из формы pvs, так как он вычисляется автоматически во время компиляции.

Единственный флаг, используемый в настоящее время из параметра flags, — COPHH_KEY_UTF8. Запрещено устанавливать его в форме sv. В формах pv*, он указывает, интерпретируются ли байты ключа как UTF-8 (если установлен) или как Latin-1 (если сброшен). Форма sv использует базовый SV для определения UTF-8ности байтов.

COPHH *  cophh_delete_pv (COPHH *cophh, const char *key, U32 hash,
                          U32 flags)
COPHH *  cophh_delete_pvn(COPHH *cophh, const char *key,
                          STRLEN keylen, U32 hash, U32 flags)
COPHH *  cophh_delete_pvs(COPHH *cophh, "key", U32 flags)
COPHH *  cophh_delete_sv (COPHH *cophh, SV *key, U32 hash,
                          U32 flags)
cophh_exists_pvn

ПРИМЕЧАНИЕ: cophh_exists_pvn является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Выполняют поиск записи подсказки в cop cop с ключом, указанным key (и keylen в форме pvn), возвращая true, если значение существует, и false в противном случае.

Формы различаются тем, как задаётся ключ. В обычной форме pv, ключ — это C-строка с завершающим нулём. В форме pvs, ключ — это C-строковый литерал. В форме pvn, дополнительный параметр keylen указывает длину строки, которая, следовательно, может содержать вставленные нули. В форме sv, *key — это SV, и ключ — это PV, извлечённый из него, используя "SvPV_const".

hash — это предварительно вычисленный хеш строки ключа или ноль, если он не был предварительно вычислен. Этот параметр опущен из формы pvs, так как он вычисляется автоматически во время компиляции.

Единственный флаг, используемый в настоящее время из параметра flags, — COPHH_KEY_UTF8. Запрещено устанавливать его в форме sv. В формах pv*, он указывает, интерпретируются ли байты ключа как UTF-8 (если установлен) или как Latin-1 (если сброшен). Форма sv использует базовый SV для определения UTF-8ности байтов.

bool  cophh_exists_pvn(const COPHH *cophh, const char *key,
                       STRLEN keylen, U32 hash, U32 flags)
cophh_fetch_pv
cophh_fetch_pvn
cophh_fetch_pvs
cophh_fetch_sv

ПРИМЕЧАНИЕ: все эти формы являются экспериментальными и могут быть изменены или удалены без предварительного уведомления.

Выполняют поиск записи в хеше подсказок cop cophh с ключом, указанным key (и keylen в форме pvn), возвращая это значение как смертную копию скалярной переменной или &PL_sv_placeholder, если значение, связанное с ключом, отсутствует.

Формы различаются тем, как задаётся ключ. В обычной форме pv, ключ представляет собой C-строку с завершающим нулём. В форме pvs, ключ представляет собой C-строковый литерал. В форме pvn, дополнительный параметр keylen указывает длину строки, которая, следовательно, может содержать вставленные нули. В форме sv, *key является SV, и ключ — это PV, извлечённый из него, используя "SvPV_const".

hash — это предварительно вычисленный хеш строки ключа или ноль, если он не был предварительно вычислен. Этот параметр опущен из формы pvs, так как он вычисляется автоматически во время компиляции.

Единственный флаг, используемый в настоящее время из параметра flags, — COPHH_KEY_UTF8. Запрещено устанавливать его в форме sv. В формах pv*, он указывает, интерпретируются ли байты ключа как UTF-8 (если установлен) или как Latin-1 (если сброшен). Форма sv использует базовый SV для определения UTF-8ности байтов.

SV *  cophh_fetch_pv (const COPHH *cophh, const char *key,
                      U32 hash, U32 flags)
SV *  cophh_fetch_pvn(const COPHH *cophh, const char *key,
                      STRLEN keylen, U32 hash, U32 flags)
SV *  cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags)
SV *  cophh_fetch_sv (const COPHH *cophh, SV *key, U32 hash,
                      U32 flags)
cophh_free

ПРИМЕЧАНИЕ: cophh_free является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Отбрасывает хеш подсказок cop cophh, освобождая все ресурсы, связанные с ним.

void  cophh_free(COPHH *cophh)
cophh_2hv

ПРИМЕЧАНИЕ: cophh_2hv является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Генерирует и возвращает стандартный Perl-хеш, представляющий полную совокупность пар ключ/значение в хеше подсказок cop cophh. flags в настоящее время не используется и должен быть нулём.

HV *  cophh_2hv(const COPHH *cophh, U32 flags)
cophh_new_empty

ПРИМЕЧАНИЕ: cophh_new_empty является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Генерирует и возвращает свежий хеш подсказок cop, не содержащий записей.

COPHH *  cophh_new_empty()
cophh_store_pv
cophh_store_pvn
cophh_store_pvs
cophh_store_sv

ПРИМЕЧАНИЕ: все эти формы являются экспериментальными и могут быть изменены или удалены без предварительного уведомления.

Эти функции сохраняют значение, связанное с ключом, в хеше подсказок cop cophh, и возвращают изменённый хеш. Указатель на возвращённый хеш, как правило, отличается от указателя на переданный хеш. Входной хеш потребляется функцией, и указатель на него не должен использоваться в дальнейшем. Используйте "cophh_copy", если вам нужны оба хеша.

value — это скалярное значение для сохранения по этому ключу. value копируется этими функциями, которые таким образом не берут на себя ответственность за любую ссылку на него, и поэтому последующие изменения скаляра не будут отражены в значении, видимом в хеше подсказок cop. Сложные типы скаляров не будут сохраняться с целостностью ссылок, а будут преобразованы в строки.

Формы различаются тем, как задаётся ключ. Во всех формах ключ указывается через key. В обычной форме pv, ключ представляет собой C-строку с завершающим нулём. В форме pvs, ключ представляет собой C-строку-литерал. В форме pvn, дополнительный параметр keylen указывает длину строки, которая, следовательно, может содержать вставленные нули. В форме sv, *key является SV, и ключ — это PV, извлечённый из него, используя "SvPV_const".

hash — это предварительно вычисленный хеш строки ключа или ноль, если он не был предварительно вычислен. Этот параметр опущен из формы pvs, так как он вычисляется автоматически во время компиляции.

Единственный флаг, используемый в настоящее время из параметра flags, — COPHH_KEY_UTF8. Запрещено устанавливать его в форме sv. В формах pv*, он указывает, интерпретируются ли байты ключа как UTF-8 (если установлен) или как Latin-1 (если сброшен). Форма sv использует базовый SV для определения UTF-8ности байтов.

COPHH *  cophh_store_pv (COPHH *cophh, const char *key, U32 hash,
                         SV *value, U32 flags)
COPHH *  cophh_store_pvn(COPHH *cophh, const char *key,
                         STRLEN keylen, U32 hash, SV *value,
                         U32 flags)
COPHH *  cophh_store_pvs(COPHH *cophh, "key", SV *value,
                         U32 flags)
COPHH *  cophh_store_sv (COPHH *cophh, SV *key, U32 hash,
                         SV *value, U32 flags)
cop_hints_exists_pv
cop_hints_exists_pvn
cop_hints_exists_pvs
cop_hints_exists_sv

Эти функции ищут запись подсказки в копе cop с ключом, заданным key (и keylen в форме pvn), возвращая true, если значение существует, и false в противном случае.

Формы отличаются тем, как задаётся ключ. Во всех формах ключ указан key. В обычной форме pv, ключ — это строка C языка с завершающим нулём. В форме pvs, ключ — это строковая литерал языка C. В форме pvn, дополнительный параметр keylen указывает длину строки, которая может содержать вложенные нули. В форме sv, *key — это SV, и ключ — это PV, извлечённый из него с помощью "SvPV_const".

hash — это предварительно вычисленный хеш строки ключа или ноль, если он не был предварительно вычислен. Этот параметр опущен в форме pvs, так как он вычисляется автоматически во время компиляции.

Единственный флаг, используемый в настоящее время из параметра flags, — COPHH_KEY_UTF8. Его запрещено устанавливать в форме sv. В формах pv*, он определяет, интерпретируются ли байты ключа как UTF-8 (если установлен) или как Latin-1 (если сброшен). Форма sv использует базовый SV для определения UTF-8-ности байтов.

bool  cop_hints_exists_pv (const COP *cop, const char *key,
                           U32 hash, U32 flags)
bool  cop_hints_exists_pvn(const COP *cop, const char *key,
                           STRLEN keylen, U32 hash, U32 flags)
bool  cop_hints_exists_pvs(const COP *cop, "key", U32 flags)
bool  cop_hints_exists_sv (const COP *cop, SV *key, U32 hash,
                           U32 flags)
cop_hints_fetch_pv
cop_hints_fetch_pvn
cop_hints_fetch_pvs
cop_hints_fetch_sv

Эти функции ищут запись подсказки в копе cop с ключом, заданным key (и keylen в форме pvn). Они возвращают значение в виде смертельной скалярной копии или &PL_sv_placeholder, если для ключа нет значения.

Формы отличаются тем, как задаётся ключ. В обычной форме pv, ключ — это строка C языка с завершающим нулём. В форме pvs, ключ — это строковая литерал языка C. В форме pvn, дополнительный параметр keylen указывает длину строки, которая может содержать вложенные нули. В форме sv, *key — это SV, а ключ — это PV, извлечённый из него с помощью "SvPV_const".

hash — это предварительно вычисленный хеш строки ключа или ноль, если он не был предварительно вычислен. Этот параметр опущен в форме pvs, так как он вычисляется автоматически во время компиляции.

Единственный флаг, используемый в настоящее время из параметра flags, — COPHH_KEY_UTF8. Его запрещено устанавливать в форме sv. В формах pv*, он определяет, интерпретируются ли байты ключа как UTF-8 (если установлен) или как Latin-1 (если сброшен). Форма sv использует базовый SV для определения UTF-8-ности байтов.

SV *  cop_hints_fetch_pv (const COP *cop, const char *key,
                          U32 hash, U32 flags)
SV *  cop_hints_fetch_pvn(const COP *cop, const char *key,
                          STRLEN keylen, U32 hash, U32 flags)
SV *  cop_hints_fetch_pvs(const COP *cop, "key", U32 flags)
SV *  cop_hints_fetch_sv (const COP *cop, SV *key, U32 hash,
                          U32 flags)
cop_hints_2hv

Генерирует и возвращает стандартный Perl-хеш, представляющий полный набор записей подсказок в копе cop. flags в настоящее время не используется и должен быть равен нулю.

HV *  cop_hints_2hv(const COP *cop, U32 flags)
CopLABEL
CopLABEL_len
CopLABEL_len_flags

Эти функции возвращают метку, присоединённую к копу.

CopLABEL_len и CopLABEL_len_flags дополнительно сохраняют количество байтов, составляющих возвращаемую метку, в *len.

CopLABEL_len_flags дополнительно возвращает UTF-8-ность возвращаемой метки, устанавливая *flags в 0 или SVf_UTF8.

const char *  CopLABEL          (COP *const cop)
const char *  CopLABEL_len      (COP *const cop, STRLEN *len)
const char *  CopLABEL_len_flags(COP *const cop, STRLEN *len,
                                 U32 *flags)
CopLINE

Возвращает номер строки в исходном коде, связанный с COP c

line_t  CopLINE(const COP * c)
CopSTASH

Возвращает хранилище, связанное с c.

HV *  CopSTASH(const COP * c)
CopSTASH_eq

Возвращает булево значение, указывающее, является ли hv хранилищем, связанным с c.

bool  CopSTASH_eq(const COP * c, const HV * hv)
CopSTASHPV

Возвращает имя пакета хранилища, связанного с c, или NULL, если соответствующее хранилище отсутствует.

char *  CopSTASHPV(const COP * c)
CopSTASHPV_set

Устанавливает имя пакета хранилища, связанного с c, на строку C с завершающим нулём p, создавая пакет при необходимости.

void  CopSTASHPV_set(COP * c, const char * pv)
CopSTASH_set

Устанавливает хранилище, связанное с c, на hv.

bool  CopSTASH_set(COP * c, HV * hv)
cop_store_label

ПРИМЕЧАНИЕ: cop_store_label является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Сохраняет метку в cop_hints_hash. Для метки UTF-8 необходимо установить флаги на SVf_UTF8. Любые другие флаги игнорируются.

void  cop_store_label(COP * const cop, const char *label,
                      STRLEN len, U32 flags)
PERL_SI

Используйте этот typedef для объявления переменных, которые должны хранить struct stackinfo.

PL_curcop

Текущий активный COP (оператор управления), примерно представляющий текущее утверждение в исходном коде.

В потоковых Perl, каждый поток имеет независимую копию этой переменной; каждый инициализирован при создании с текущим значением копии создающего потока.

COP*  PL_curcop
RCPV_LEN

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

RCPV *  RCPV_LEN(char *pv)
RCPV_REFCNT_dec

Уменьшает счётчик ссылок для указателя char *, созданного вызовом rcpv_new(). То же самое, что вызов rcpv_free(). Проверки, что pv был фактически выделен с помощью rcpv_new(), не выполняются; ответственность за это лежит на вызывающем объекте.

RCPV *  RCPV_REFCNT_dec(char *pv)
RCPV_REFCNT_inc

Увеличивает счётчик ссылок для указателя char *, созданного вызовом rcpv_new(). То же самое, что вызов rcpv_copy(). Проверки, что pv был фактически выделен с помощью rcpv_new(), не выполняются; ответственность за это лежит на вызывающем объекте.

RCPV *  RCPV_REFCNT_inc(char *pv)
RCPV_REFCOUNT

Возвращает счётчик ссылок для pv, созданного с помощью rcpv_new(). Проверки, что pv был фактически выделен с помощью rcpv_new(), не выполняются; ответственность за это лежит на вызывающем объекте.

RCPV *  RCPV_REFCOUNT(char *pv)
RCPVx

Возвращает структуру RCPV (struct rcpv) для указателя на строку с подсчётом ссылок pv, созданного с помощью rcpv_new(). Проверки, что pv был фактически выделен с помощью rcpv_new(), не выполняются; ответственность за это лежит на вызывающем объекте.

RCPV *  RCPVx(char *pv)

Операторы пользовательского определения

custom_op_register

Регистрация оператора пользовательского определения. См. "Операторы пользовательского определения" в perlguts.

ПРИМЕЧАНИЕ: custom_op_register должен быть явно вызван как Perl_custom_op_register с параметром aTHX_.

void  Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr,
                              const XOP *xop)
Perl_custom_op_xop

Возвращает структуру XOP для данного оператора пользовательского определения. Этот макрос следует считать внутренним для OP_NAME и других макросов доступа: используйте их вместо него. Этот макрос вызывает функцию. До версии 5.19.6, это была функция.

const XOP *  Perl_custom_op_xop(pTHX_ const OP *o)
XopDISABLE

Временное отключение члена XOP путём сброса соответствующего флага.

void  XopDISABLE(XOP *xop, token which)
XopENABLE

Возобновление работы члена XOP, который был отключён.

void  XopENABLE(XOP *xop, token which)
XopENTRY

Возвращает член структуры XOP. which — это cpp-токен, указывающий, какой элемент нужно вернуть. Если член не установлен, будет возвращено значение по умолчанию. Тип возвращаемого значения зависит от which. Этот макрос вычисляет свои аргументы более одного раза. Если вы используете Perl_custom_op_xop для получения XOP * из OP *, используйте более эффективную функцию "XopENTRYCUSTOM" вместо этого.

XopENTRY(XOP *xop, token which)
XopENTRYCUSTOM

Точно так же, как XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o), which), но более эффективно. Параметр which идентичен "XopENTRY".

XopENTRYCUSTOM(const OP *o, token which)
XopENTRY_set

Установка члена структуры XOP. which — это cpp-токен, указывающий, какой элемент нужно установить. См. "Операторы пользовательского определения" в perlguts для получения подробной информации о доступных членах и способе их использования. Этот макрос вычисляет свои аргументы более одного раза.

void  XopENTRY_set(XOP *xop, token which, value)
XopFLAGS

Возвращает флаги XOP.

U32  XopFLAGS(XOP *xop)

Обработка CV

В этом разделе описываются функции для манипулирования CV (значения кода), которые являются подпрограммами. Дополнительную информацию см. в perlguts.

caller_cx

Аналог функции caller() для XSUB-авторов. Возвращаемая структура PERL_CONTEXT может быть использована для получения всей информации, возвращаемой Perl функцией caller. Обратите внимание, что XSUB не имеют кадра стека, поэтому caller_cx(0, NULL) вернёт информацию для непосредственно окружающего Perl-кода.

Эта функция пропускает автоматические вызовы &DB::sub, выполняемые от имени отладчика. Если запрашиваемый кадр стека был вызван подпрограммой DB::sub, возвращаемое значение будет кадром для вызова подпрограммы DB::sub, так как у него правильный номер строки и т. д. для места вызова. Если dbcxp не NULL, он будет установлен в указатель на кадр для вызова подпрограммы.

const PERL_CONTEXT *  caller_cx(I32 level,
                                const PERL_CONTEXT **dbcxp)
END_OF_DOCUMENT_MARKER
CvDEPTH

Возвращает уровень рекурсии CV sv. Значение >= 2 указывает на рекурсивный вызов.

I32 *  CvDEPTH(const CV * const sv)
CvGV

Возвращает GV, связанный с CV sv, реабилитируя его при необходимости.

GV *  CvGV(CV *sv)
CvSTASH

Возвращает стек CV. Стек — это хеш-таблица символов, содержащая переменные, относящиеся к пакету, в котором была определена подпрограмма. Дополнительную информацию см. в perlguts.

Также используется со XSUB AUTOLOAD-подпрограммами. См. "Автозагрузка с XSUB" в perlguts.

HV*  CvSTASH(CV* cv)
find_runcv

Находит CV, соответствующий текущей исполняемой подпрограмме или eval. Если db_seqp не null, пропускаются CV в пакете DB и *db_seqp заполняется порядковым номером обработки в момент входа в код DB::. (Это позволяет отладчикам выполнять eval в области действия точки останова, а не в области действия самого отладчика.)

CV *  find_runcv(U32 *db_seqp)
get_cv
get_cvn_flags
get_cvs

Эти функции возвращают CV указанной подпрограммы Perl. flags передаются gv_fetchpvn_flags. Если GV_ADD установлено и подпрограмма Perl не существует, она будет объявлена (что эквивалентно sub name;). Если GV_ADD не установлено и подпрограмма не существует, возвращается NULL.

Форматы различаются только способом задания имени подпрограммы. В get_cvs, имя — это строковая константа C, заключенная в двойные кавычки. В get_cv, имя задаётся параметром name, который должен быть C-строкой с завершающим нулём. В get_cvn_flags, имя задаётся параметром name, но это строка Perl (возможно, содержащая вложенные нули), а её длина в байтах содержится в параметре len.

ПРИМЕЧАНИЕ: форма perl_get_cv() устаревшая.

ПРИМЕЧАНИЕ: форма perl_get_cvn_flags() устаревшая.

ПРИМЕЧАНИЕ: форма perl_get_cvs() устаревшая.

CV *  get_cv       (const char *name, I32 flags)
CV *  get_cvn_flags(const char *name, STRLEN len, I32 flags)
CV *  get_cvs      ("string", I32 flags)
Nullcv

DEPRECATED! Планируется удалить Nullcv в будущих версиях Perl. Не используйте её в новом коде; удалите из существующего.

Указатель на нулевой CV.

(устаревшее - используйте (CV *)NULL вместо этого)

Отладка

av_dump

Выводит содержимое AV в файл STDERR. Аналогично Devel::Peek на arrayref, но не ожидает обёртки RV. Вывод до глубины 3 уровней.

void  av_dump(AV *av)
deb
deb_nocontext

Когда perl скомпилирован с -DDEBUGGING, это выводит в STDERR информацию, предоставленную аргументами, с префиксом из имени файла, содержащего скрипт, вызвавший вызов, и номера строки в этом файле.

Если включен параметр отладки v (подробности), также выводится идентификатор процесса.

Различия между двумя формами в том, что deb_nocontext не принимает параметр контекста потока (aTHX), поэтому используется в ситуациях, когда у вызывающей стороны нет контекста потока.

ПРИМЕЧАНИЕ: deb необходимо явно вызывать как Perl_deb с параметром aTHX_.

void  Perl_deb     (pTHX_ const char *pat, ...)
void  deb_nocontext(const char *pat, ...)
debstack

Выводит текущий стек

I32  debstack()
dump_all

Выводит весь optree текущей программы, начиная с PL_main_root до STDERR. Также выводит optree всех видимых подпрограмм в PL_defstash.

void  dump_all()
dump_c_backtrace

Выводит C-стек вызовов в указанный fp.

Возвращает true, если стек вызовов был получен, и false — в противном случае.

bool  dump_c_backtrace(PerlIO *fp, int max_depth, int skip)
dump_eval

Описание в perlguts.

void  dump_eval()
dump_form

Выводит содержимое формата, содержащегося в GV gv в STDERR, или сообщение, что такой не существует.

void  dump_form(const GV *gv)
dump_packsubs

Выводит optree для всех видимых подпрограмм в stash.

void  dump_packsubs(const HV *stash)
dump_sub

Описание в perlguts.

void  dump_sub(const GV *gv)
get_c_backtrace_dump

Возвращает SV, содержащий вывод depth фреймов стека вызовов, пропуская skip внутренних фреймов. depth 20 обычно достаточно.

Выводимый результат выглядит следующим образом:

...
1   10e004812:0082   Perl_croak   util.c:1716    /usr/bin/perl
2   10df8d6d2:1d72   perl_parse   perl.c:3975    /usr/bin/perl
...

Поля разделены табуляцией. Первый столбец — глубина (нуль — внутренний фрейм, не пропускаемый). В шестнадцатеричном:смещении, шестнадцатеричное значение — это значение счётчика команд в S_parse_body, а :смещение (может отсутствовать) показывает, насколько внутрь S_parse_body смещён счётчик команд.

util.c:1716 — файл исходного кода и номер строки.

/usr/bin/perl очевиден (надеюсь).

Неизвестные значения — "-". К сожалению, неизвестные значения могут возникать довольно легко: если платформа не поддерживает извлечение информации; если в двоичном файле отсутствуют отладочные данные; если оптимизатор преобразовал код, например, посредством встраивания.

SV *  get_c_backtrace_dump(int max_depth, int skip)
gv_dump

Выводит имя и, если они отличаются, эффективное имя GV gv в STDERR.

void  gv_dump(GV *gv)
HAS_BACKTRACE

Этот символ, если определён, указывает, что процедура backtrace() доступна для получения стека вызовов. Для использования этой процедуры необходимо включить заголовок execinfo.h.

hv_dump

Выводит содержимое HV в файл STDERR. Аналогично Devel::Peek на hashref, но не ожидает обёртки RV. Вывод до глубины 3 уровней.

void  hv_dump(HV *hv)
magic_dump

Выводит содержимое MAGIC mg в STDERR.

void  magic_dump(const MAGIC *mg)
op_class

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

OPclass  op_class(const OP *o)
op_dump

Выводит optree, начиная с OP o в STDERR.

void  op_dump(const OP *o)
PL_op

Описание в perlhacktips.

PL_runops

Описание в perlguts.

PL_sv_serial

Описание в perlhacktips.

pmop_dump

Выводит OP, связанный с сопоставлением шаблонов, например, s/foo/bar/; они требуют специального обработки.

void  pmop_dump(PMOP *pm)
sv_dump

Выводит содержимое SV в файл STDERR.

Пример вывода см. в Devel::Peek. Если элемент — SvROK, он выводит элементы до глубины 4, в противном случае выводит только верхний уровень, что означает, что он не выводит содержимое AV * или HV *. Для этого используйте av_dump() или hv_dump().

void  sv_dump(SV *sv)
sv_dump_depth

Выводит содержимое SV в файл STDERR на запрошенную глубину. Эта функция может быть использована с любым типом SV, производным от (GV, HV, AV), с соответствующей приведённой. Это более гибкая версия sv_dump(). Например

HV *hv = ...;
sv_dump_depth((SV*)hv, 2);

выведет hv, его ключи и значения, но не будет рекурсивно выводить значения RV.

void  sv_dump_depth(SV *sv, I32 depth)
vdeb

Это похоже на "deb", но args — это упакованный список аргументов.

void  vdeb(const char *pat, va_list *args)

Функции отображения

form
form_nocontext

Они принимают шаблон форматирования в стиле sprintf и обычные (не SV) аргументы и возвращают отформатированную строку.

(char *) Perl_form(pTHX_ const char* pat, ...)

может использоваться в любом месте, где требуется строка (char *):

char * s = Perl_form("%d.%d",major,minor);

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

Различия между двумя формами заключаются в том, что form_nocontext не принимает параметр контекста потока (aTHX), поэтому используется в ситуациях, когда у вызывающей стороны уже есть контекст потока.

ПРИМЕЧАНИЕ: form необходимо явно вызывать как Perl_form с параметром aTHX_.

char *  Perl_form     (pTHX_ const char *pat, ...)
char *  form_nocontext(const char *pat, ...)
mess
mess_nocontext

Они принимают шаблон форматирования в стиле sprintf и список аргументов, которые используются для создания сообщения. Если сообщение не заканчивается символом новой строки, оно будет дополнено указанием текущего местоположения в коде, как описано для "mess_sv".

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

Различия между двумя формами заключаются в том, что mess_nocontext не принимает параметр контекста потока (aTHX), поэтому используется в ситуациях, когда у вызывающей стороны уже есть контекст потока.

ПРИМЕЧАНИЕ: mess необходимо явно вызывать как Perl_mess с параметром aTHX_.

SV *  Perl_mess     (pTHX_ const char *pat, ...)
SV *  mess_nocontext(const char *pat, ...)
mess_sv

Расширяет сообщение, предназначенное для пользователя, чтобы включить указание текущего местоположения в коде, если сообщение, по-видимому, ещё не является полным.

basemsg — это исходное сообщение или объект. Если это ссылка, она будет использована как есть и станет результатом этой функции. В противном случае она используется как строка, и если она уже заканчивается новой строкой, считается полной, и результат этой функции будет той же строкой. Если сообщение не заканчивается новой строкой, то будет добавлен фрагмент, такой как at foo.pl line 37, а также, возможно, другие фразы, указывающие текущее состояние выполнения. Результирующее сообщение будет заканчиваться точкой и новой строкой.

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

SV *  mess_sv(SV *basemsg, bool consume)
pv_display

Аналогично

pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);

кроме того, что дополнительный символ "\0" будет добавлен к строке, когда len > cur и pv[cur] равняется "\0".

Обратите внимание, что конечная строка может быть на 7 символов длиннее, чем pvlim.

char *  pv_display(SV *dsv, const char *pv, STRLEN cur,
                   STRLEN len, STRLEN pvlim)
pv_escape

Экранирует не более первых count символов pv и помещает результаты в dsv, при этом размер закодированной строки не будет превышать max символов и не будет содержать неполных последовательностей экранирования. Количество закодированных байтов будет возвращено в параметре STRLEN *escaped, если он не равен NULL. Если параметр dsv равен NULL, экранирование не выполняется, но рассчитывается количество байтов, которые были бы закодированы, если бы он не был NULL.

Если флаги содержат PERL_PV_ESCAPE_QUOTE, то любые двойные кавычки в строке также будут экранированы.

Обычно SV очищается перед подготовкой закодированной строки, но при установке PERL_PV_ESCAPE_NOCLEAR этого не произойдёт.

Если установлено PERL_PV_ESCAPE_UNI, входная строка обрабатывается как UTF-8. Если установлено PERL_PV_ESCAPE_UNI_DETECT, входная строка сканируется с помощью is_utf8_string(), чтобы определить, является ли она UTF-8.

Если установлено PERL_PV_ESCAPE_ALL, все символы ввода будут выведены с помощью экранирования в стиле \x01F1, в противном случае, если установлено PERL_PV_ESCAPE_NONASCII, только не-ASCII символы будут экранированы в этом стиле; в противном случае только символы с кодами выше 255 будут так экранированы; другие непечатаемые символы будут использовать восьмеричное представление или стандартные закодированные шаблоны, такие как \n. В противном случае, если установлено PERL_PV_ESCAPE_NOBACKSLASH, все символы с кодами ниже 255 будут обрабатываться как печатаемые и выводиться как литералы. PERL_PV_ESCAPE_NON_WC изменяет предыдущие правила, чтобы привести символы слова (Unicode или другие) к литеральным значениям, при этом используется *Unicode*-правила для определения символов слова.

Если установлено PERL_PV_ESCAPE_FIRSTCHAR, будет экранирован только первый символ строки, независимо от max. Если вывод должен быть в шестнадцатеричном формате, он будет возвращён как обычная шестнадцатеричная последовательность. Таким образом, выводом будет либо один символ, восьмеричная последовательность экранирования, специальный символ экранирования, такой как \n, или шестнадцатеричное значение.

Если установлено PERL_PV_ESCAPE_RE, используемый символ экранирования будет "%", а не "\\". Это связано с тем, что выражения регулярных выражений часто содержат последовательности с обратным слэшем, в то время как "%" — не очень распространённый символ в шаблонах.

Возвращает указатель на закодированный текст, хранящийся в dsv.

char *  pv_escape(SV *dsv, char const * const str,
                  const STRLEN count, STRLEN max,
                  STRLEN * const escaped, U32 flags)
pv_pretty

Преобразует строку в удобочитаемый вид, обрабатывая экранирование через pv_escape() и поддерживая кавычки и многоточие.

Если установлен флаг PERL_PV_PRETTY_QUOTE, результат будет заключён в двойные кавычки, а все двойные кавычки в строке будут экранированы. В противном случае, если установлен флаг PERL_PV_PRETTY_LTGT, результат будет заключён в угловые скобки.

Если установлен флаг PERL_PV_PRETTY_ELLIPSES и не все символы в строке были выведены, то к строке будет добавлен многоточие .... Обратите внимание, что это происходит *после* добавления кавычек.

Если start_color не равно NULL, оно будет вставлено после открывающей кавычки (если она есть), но перед закодированным текстом. Если end_color не равно NULL, оно будет вставлено после закодированного текста, но перед кавычками или многоточием.

Возвращает указатель на отформатированный текст, хранящийся в dsv.

char *  pv_pretty(SV *dsv, char const * const str,
                  const STRLEN count, const STRLEN max,
                  char const * const start_color,
                  char const * const end_color, const U32 flags)
vform

Подобно "form", но аргументы представляют собой упакованный список аргументов.

char *  vform(const char *pat, va_list *args)
vmess

pat и args — это шаблон формата в стиле sprintf и упакованный список аргументов соответственно. Они используются для генерации строкового сообщения. Если сообщение не заканчивается новой строкой, то оно будет дополнено указанием текущего местоположения в коде, как описано для "mess_sv".

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

SV *  vmess(const char *pat, va_list *args)

Встраивание, Потоки и Клонирование Интерпретатора

call_atexit

Добавляет функцию fn в список функций, которые должны быть вызваны при глобальном уничтожении. ptr будет передано в качестве аргумента fn; он может указывать на struct для передачи любых необходимых данных.

Обратите внимание, что в потоках fn может быть запущено несколько раз. Это происходит, потому что список выполняется каждый раз, когда завершается текущий или любой дочерний поток.

void  call_atexit(ATEXIT_t fn, void *ptr)
cv_clone

Клонирует CV, создавая лексическое замыкание. proto предоставляет шаблон функции: её код, структуру стека и другие атрибуты. Шаблон комбинируется со сбором внешних лексических элементов, к которым относится код, которые берутся из текущего экземпляра окружающего кода.

CV *  cv_clone(CV *proto)
cv_name

Возвращает SV, содержащий имя CV, в основном для использования в сообщениях об ошибках. CV фактически может быть GV, в этом случае возвращаемый SV содержит имя GV. Любой элемент, кроме GV или CV, рассматривается как строка, уже содержащая имя подпрограммы, но это может измениться в будущем.

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

Если flags имеет бит CV_NAME_NOTQUAL, имя пакета не будет включено. Если первый аргумент не является ни CV, ни GV, этот флаг игнорируется (может быть изменено).

SV *  cv_name(CV *cv, SV *sv, U32 flags)
cv_undef

Очищает все активные компоненты CV. Это может произойти либо явным undef &foo, либо при уменьшении счётчика ссылок до нуля. В первом случае, мы сохраняем указатель CvOUTSIDE, так что любые анонимные дочерние элементы могут по-прежнему следовать полной цепочке лексического охвата.

void  cv_undef(CV *cv)
find_rundefsv

Возвращает глобальную переменную $_.

SV *  find_rundefsv()
get_op_descs

DEPRECATED! Планируется удалить get_op_descs в будущих версиях Perl. Не используйте его для нового кода; удалите его из существующего кода.

Возвращает указатель на массив всех описаний различных OP. При заданном коде операции из перечисления в opcodes.h, PL_op_desc[opcode] возвращает указатель на строку C языка, содержащую его описание.

char **  get_op_descs()
get_op_names

DEPRECATED! Планируется удалить get_op_names в будущих версиях Perl. Не используйте его для нового кода; удалите его из существующего кода.

Возвращает указатель на массив всех имён различных OP. При заданном коде операции из перечисления в opcodes.h, PL_op_name[opcode] возвращает указатель на строку C языка, содержащую его имя.

char **  get_op_names()
HAS_SKIP_LOCALE_INIT

Описание в perlembed.

intro_my

«Представляет» my переменные для видимости. Это вызывается во время парсинга в конце каждой строки, чтобы сделать лексические переменные видимыми последующим строкам.

U32  intro_my()
load_module
load_module_nocontext

Загружают модуль, имя которого указано в строковой части name. Обратите внимание, что должно быть указано фактическое имя модуля, а не его имя файла. Например, «Foo::Bar», а не «Foo/Bar.pm». ver, если указан и не равен NULL, предоставляет семантику версий, аналогичную use Foo::Bar VERSION. Дополнительные необязательные аргументы могут быть использованы для указания аргументов метода import() модуля, аналогично use Foo::Bar VERSION LIST; их точная обработка зависит от флагов. Аргумент flags — это битовое ИЛИ из любых из PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, или PERL_LOADMOD_IMPORT_OPS (или 0 для отсутствия флагов).

Если установлено PERL_LOADMOD_NOIMPORT, модуль загружается так, как если бы импортный список был пустым, как в use Foo::Bar (); это единственный случай, когда необязательные последующие аргументы могут быть полностью опущены. В противном случае, если установлено PERL_LOADMOD_IMPORT_OPS, последующие аргументы должны состоять точно из одного OP*, содержащего дерево OP, которое генерирует соответствующие аргументы импорта. В противном случае последующие аргументы должны быть значениями SV*, которые будут использованы в качестве аргументов импорта; и список должен заканчиваться (SV*) NULL. Если ни PERL_LOADMOD_NOIMPORT, ни PERL_LOADMOD_IMPORT_OPS не установлены, указатель NULL необходим даже если не требуются аргументы импорта. Счётчик ссылок для каждого указанного аргумента SV* уменьшается. Кроме того, аргумент name изменяется.

Если установлено PERL_LOADMOD_DENY, модуль загружается так, как если бы с no, а не use.

load_module и load_module_nocontext имеют одинаковую видимую сигнатуру, но первый скрывает тот факт, что он обращается к параметру контекста потока. Поэтому используйте последний, когда вы получаете ошибку компиляции о pTHX.

void  load_module          (U32 flags, SV *name, SV *ver, ...)
void  load_module_nocontext(U32 flags, SV *name, SV *ver, ...)
my_exit

Обёртка для функции C-библиотеки exit(3), учитывая то, что сказано в "PL_exit_flags" в perlapi.

void  my_exit(U32 status)
END_OF_DOCUMENT_MARKER
my_failure_exit

Выход из работающего процесса Perl с ошибкой.

На платформах, отличных от VMS, это по сути эквивалентно "my_exit", используя errno, но принудительно устанавливает код ошибки 255, если errno равно 0.

В VMS это заботится об установке соответствующих битов уровня серьезности в статусе выхода.

void  my_failure_exit()
my_strlcat

Библиотека C strlcat (если доступна) или её реализация на Perl. Работает со строками C NUL-завершёнными строками.

my_strlcat() добавляет строку src в конец строки dst. Будет добавлено не более size - strlen(dst) - 1 символов. Затем она будет NUL-завершённой, если size не равно 0 и исходная строка dst была короче size (на практике это не должно происходить, так как это означает, что либо size неверно, либо dst не является правильно NUL-завершённой строкой).

Обратите внимание, что size — это полный размер буфера назначения, и результат гарантированно будет NUL-завершённым, если есть место. Убедитесь, что NUL входит в size.

Возвращаемое значение — это общая длина, которую dst имела бы, если бы size была достаточно большой. Таким образом, это начальная длина dst плюс длина src. Если size меньше возвращаемого значения, избыток не был добавлен.

Size_t  my_strlcat(char *dst, const char *src, Size_t size)
my_strlcpy

Библиотека C strlcpy (если доступна) или её реализация на Perl. Работает со строками C NUL-завершёнными строками.

my_strlcpy() копирует не более size - 1 символов из строки src в dst, NUL-завершая результат, если size не равно 0.

Возвращаемое значение — это общая длина, которую src имела бы, если бы копирование прошло полностью успешно. Если оно больше size, избыток не был скопирован.

Size_t  my_strlcpy(char *dst, const char *src, Size_t size)
newPADNAMELIST

ПРИМЕЧАНИЕ: newPADNAMELIST является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Создаёт новый список имён областей. max — это максимальный индекс, для которого выделяется память.

PADNAMELIST *  newPADNAMELIST(size_t max)
newPADNAMEouter

ПРИМЕЧАНИЕ: newPADNAMEouter является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Создаёт и возвращает новое имя области. Используйте эту функцию только для имён, которые ссылаются на внешние лексические переменные. (См. также "newPADNAMEpvn".) outer — это имя внешней области, которое это имя отражает. Возвращаемое имя области имеет флаг PADNAMEf_OUTER уже установленным.

PADNAME *  newPADNAMEouter(PADNAME *outer)
newPADNAMEpvn

ПРИМЕЧАНИЕ: newPADNAMEpvn является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Создаёт и возвращает новое имя области. s должно быть строкой UTF-8. Не используйте эту функцию для имён областей, которые ссылаются на внешние лексические переменные. См. "newPADNAMEouter". 

PADNAME *  newPADNAMEpvn(const char *s, STRLEN len)
nothreadhook

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

int  nothreadhook()
pad_add_anon

Выделяет место в текущей области компиляции (через "pad_alloc") для анонимной функции, лексически вложенной внутри текущей компилируемой функции. Функция func связывается с областью, и её ссылка CvOUTSIDE на внешнюю область ослабляется, чтобы избежать цикла ссылок.

Один счётчик ссылок захватывается, поэтому вам может потребоваться сделать SvREFCNT_inc(func).

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

PADOFFSET  pad_add_anon(CV *func, I32 optype)
pad_add_name_pv

Точно так же, как "pad_add_name_pvn", но принимает строку с нулевым окончанием вместо пары строка/длина.

PADOFFSET  pad_add_name_pv(const char *name, const U32 flags,
                           HV *typestash, HV *ourstash)
pad_add_name_pvn

Выделяет место в текущей области компиляции для именованной лексической переменной. Сохраняет имя и другую метаданные в части имени области и подготавливает управление лексическим объявлением переменной. Возвращает смещение выделенного слота области.

namepv/namelen указывают имя переменной, включая ведущий знак. Если typestash не равно нулю, имя предназначено для типизированной лексической переменной, и это идентифицирует тип. Если ourstash не равно нулю, это лексическая ссылка на переменную пакета, и это идентифицирует пакет. Следующие флаги можно объединять через OR:

padadd_OUR          redundantly specifies if it's a package var
padadd_STATE        variable will retain value persistently
padadd_NO_DUP_CHECK skip check for lexical shadowing
padadd_FIELD        specifies that the lexical is a field for a class
PADOFFSET  pad_add_name_pvn(const char *namepv, STRLEN namelen,
                            U32 flags, HV *typestash,
                            HV *ourstash)
pad_add_name_sv

Точно так же, как "pad_add_name_pvn", но принимает строку имени в виде SV вместо пары строка/длина.

PADOFFSET  pad_add_name_sv(SV *name, U32 flags, HV *typestash,
                           HV *ourstash)
pad_alloc

ПРИМЕЧАНИЕ: pad_alloc является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Выделяет место в текущей области компиляции, возвращая смещение выделенного слота области. Имя изначально не прикреплено к слоту области. tmptype — это набор флагов, указывающих на требуемый тип записи в области, который будет установлен в значении SV для выделенного слота области:

SVs_PADMY    named lexical variable ("my", "our", "state")
SVs_PADTMP   unnamed temporary store
SVf_READONLY constant shared between recursion levels

SVf_READONLY поддерживается здесь только начиная с perl 5.20. Чтобы работать и с более ранними версиями, используйте SVf_READONLY|SVs_PADTMP. SVf_READONLY не делает SV в слоте области неизменяемым, а просто сообщает pad_alloc о том, что он будет сделан неизменяемым (вызывающим приложением) или, по крайней мере, должен рассматриваться как таковой.

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

PADOFFSET  pad_alloc(I32 optype, U32 tmptype)
pad_findmy_pv

Точно так же, как "pad_findmy_pvn", но принимает строку с нулевым окончанием вместо пары строка/длина.

PADOFFSET  pad_findmy_pv(const char *name, U32 flags)
pad_findmy_pvn

По заданному имени лексической переменной найти её положение в текущей области компиляции. namepv/namelen указывают имя переменной, включая ведущий знак. flags зарезервировано и должно быть равно нулю. Если переменной нет в текущей области, но она есть в области любого лексически внешнего объявления, то псевдозапись для неё добавляется в текущую область. Возвращает смещение в текущей области или NOT_IN_PAD, если такая лексическая переменная не находится в области видимости.

PADOFFSET  pad_findmy_pvn(const char *namepv, STRLEN namelen,
                          U32 flags)
pad_findmy_sv

Точно так же, как "pad_findmy_pvn", но принимает строку имени в виде SV вместо пары строка/длина.

PADOFFSET  pad_findmy_sv(SV *name, U32 flags)
padnamelist_fetch

ПРИМЕЧАНИЕ: padnamelist_fetch является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Извлекает имя области по заданному индексу.

PADNAME *  padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
padnamelist_store

ПРИМЕЧАНИЕ: padnamelist_store является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Сохраняет имя области (которое может быть null) по заданному индексу, освобождая любое существующее имя области в этом слоте.

PADNAME **  padnamelist_store(PADNAMELIST *pnl, SSize_t key,
                              PADNAME *val)
pad_tidy

ПРИМЕЧАНИЕ: pad_tidy является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Производит очистку области в конце компиляции кода, к которому она относится. Выполняемые действия: удаление большей части содержимого из областей анонимных подпрограмм-прототипов; присвоение ей @_; пометка временных переменных как таковых. type указывает тип подпрограммы:

padtidy_SUB        ordinary subroutine
padtidy_SUBCLONE   prototype for lexical closure
padtidy_FORMAT     format
void  pad_tidy(padtidy_type type)
perl_alloc

Выделяет новый интерпретатор Perl. См. perlembed.

PerlInterpreter *  perl_alloc()
PERL_ASYNC_CHECK

Описание см. в perlinterp.

void  PERL_ASYNC_CHECK()
perl_clone

Создаёт и возвращает новый интерпретатор, клонируя текущий.

perl_clone принимает следующие флаги в качестве параметров:

CLONEf_COPY_STACKS — используется для копирования стеков, без него мы просто клонируем данные и обнуляем стеки, с ним мы копируем стеки и новый интерпретатор Perl готов к работе в точном соответствии с предыдущим. Псевдо-код fork использует COPY_STACKS, в то время как threads->create — нет.

CLONEf_KEEP_PTR_TABLE — perl_clone сохраняет таблицу указателей с указателем старой переменной в качестве ключа и новой переменной в качестве значения, это позволяет проверить, была ли что-то клонировано, и не клонировать это снова, а вместо этого просто использовать значение и увеличить счётчик ссылок. Если KEEP_PTR_TABLE не установлен, perl_clone удалит таблицу указателей с помощью функции ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;. Причина сохранения таблицы указателей — если вы хотите дублировать свои собственные переменные, которые находятся вне графа, сканируемого Perl.

CLONEf_CLONE_HOST — это особенность win32, она игнорируется на Unix. Она сообщает коду win32host Perl (который написан на C++) о клонировании самого себя. Это необходимо в win32, если вы хотите запустить два потока одновременно. Если вы просто хотите сделать что-то в отдельном интерпретаторе Perl, а затем выбросить его и вернуться к исходному, вам ничего не нужно делать.

PerlInterpreter *  perl_clone(PerlInterpreter *proto_perl,
                              UV flags)
perl_construct

Инициализирует новый интерпретатор Perl. См. perlembed.

void  perl_construct(PerlInterpreter *my_perl)
perl_destruct

Закрывает интерпретатор Perl. Смотрите perlembed для учебного пособия.

my_perl указывает на интерпретатор Perl. Он должен быть предварительно создан с помощью "perl_alloc" и "perl_construct". Он мог быть инициализирован с помощью "perl_parse" и использоваться через "perl_run" и другие средства. Эта функция должна вызываться для любого интерпретатора Perl, созданного с помощью "perl_construct", даже если последующие операции над ним завершились ошибкой, например, если "perl_parse" вернула ненулевое значение.

Если у интерпретатора PL_exit_flags слово имеет PERL_EXIT_DESTRUCT_END флаг, то эта функция выполнит код в END блоках перед выполнением остальной части уничтожения. Если необходимо использовать интерпретатор между "perl_parse" и "perl_destruct" помимо вызова "perl_run", то этот флаг должен быть установлен заранее. Это важно, если "perl_run" не будет вызван или если будет выполнено что-то ещё помимо вызова "perl_run".

Возвращает значение, подходящее для передачи в функцию C-библиотеки exit (или для возврата из main), в качестве кода завершения, указывающего на характер завершения интерпретатора. Это учитывает любые ошибки "perl_parse" и любые преждевременные завершения "perl_run". Код завершения имеет тип, необходимый для операционной системы хоста, поэтому из-за различий в соглашениях о кодах завершения он не является портативным для интерпретации конкретных числовых значений как имеющих конкретные значения.

int  perl_destruct(PerlInterpreter *my_perl)
perl_free

Освобождает интерпретатор Perl. Смотрите perlembed.

void  perl_free(PerlInterpreter *my_perl)
PERL_GET_CONTEXT

Описание в perlguts.

PerlInterpreter

Описание в perlembed.

perl_parse

Указывает интерпретатору Perl проанализировать скрипт Perl. Это выполняет большую часть начальной инициализации интерпретатора Perl. Смотрите perlembed для учебного пособия.

my_perl указывает на интерпретатор Perl, который должен проанализировать скрипт. Он должен быть предварительно создан с помощью "perl_alloc" и "perl_construct". xsinit указывает на функцию обратного вызова, которая будет вызвана для настройки возможности загрузки XS-расширений этим интерпретатором Perl, или может быть равна нулю, чтобы не выполнять такую настройку.

argc и argv предоставляют набор аргументов командной строки интерпретатору Perl, как обычно передаются в функцию main программы на C. argv[argc] должно быть равно нулю. Эти аргументы указывают, где находится скрипт для анализа, либо путем именования файла скрипта, либо путем предоставления скрипта в -e опции. Если $0 будет записываться в интерпретатор Perl, то строки аргументов должны быть в области памяти для записи, и поэтому не должны быть просто строковыми константами.

env задает набор переменных среды, которые будут использоваться этим интерпретатором Perl. Если не равно нулю, оно должно указывать на нуль-терминированный массив строк среды. Если равно нулю, интерпретатор Perl будет использовать среду, предоставляемую глобальной переменной environ.

Эта функция инициализирует интерпретатор, анализирует и компилирует скрипт, указанный аргументами командной строки. Это включает выполнение кода в BEGIN, UNITCHECK, и CHECK блоках. Она не выполняет INIT блоки или основную программу.

Возвращает целое число, интерпретация которого немного сложна. Правильное использование возвращаемого значения — как булевого значения, указывающего на наличие ошибки при инициализации. Если возвращено нулевое значение, это указывает на успешную инициализацию, и можно безопасно вызвать "perl_run" и использовать его. Если возвращено ненулевое значение, это указывает на проблему, из-за которой интерпретатор хочет завершиться. Интерпретатор не должен просто быть оставлен в случае такой ошибки; вызывающий код должен корректно завершить работу интерпретатора с помощью "perl_destruct" и освободить его с помощью "perl_free".

По историческим причинам ненулевое возвращаемое значение также пытается быть подходящим значением для передачи в функцию C-библиотеки exit (или для возврата из main), в качестве кода завершения, указывающего на характер завершения инициализации. Однако это не портативно из-за различий в соглашениях о кодах завершения. Пытается вернуть код завершения, требуемый операционной системой хоста, но поскольку он ограничен ненулевым значением, не всегда возможно указать каждый тип завершения. Он надежен только в Unix, где нулевой код завершения может быть дополнен установленным битом, который будет проигнорирован. В любом случае, эта функция не является правильным местом для получения кода завершения: его следует получить из "perl_destruct".

int  perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit,
                int argc, char **argv, char **env)
perl_run

Указывает интерпретатору Perl выполнить его главную программу. Смотрите perlembed для учебного пособия.

my_perl указывает на интерпретатор Perl. Он должен быть предварительно создан с помощью "perl_alloc" и "perl_construct" и инициализирован с помощью "perl_parse". Эта функция не должна вызываться, если "perl_parse" вернула ненулевое значение, указывающее на ошибку инициализации или компиляции.

Эта функция выполняет код в INIT блоках, а затем выполняет главную программу. Код для выполнения устанавливается предыдущим вызовом "perl_parse". Если у слова интерпретатора PL_exit_flags нет флага PERL_EXIT_DESTRUCT_END, то эта функция также выполнит код в END блоках. Если необходимо выполнить дальнейшее использование интерпретатора после вызова этой функции, то END блоки должны быть отложены на время "perl_destruct" путем установки этого флага.

Возвращает целое число, интерпретация которого немного сложна. Правильное использование возвращаемого значения — как булевого значения, указывающего на то, завершилась ли программа нелокально. Если возвращено нулевое значение, это указывает, что программа завершилась успешно, и можно безопасно использовать интерпретатор (при условии, что флаг PERL_EXIT_DESTRUCT_END был установлен как описано выше). Если возвращено ненулевое значение, это указывает, что интерпретатор хочет преждевременно завершиться. Интерпретатор не должен просто быть заброшен из-за этого желания завершиться; вызывающий код должен корректно завершить работу интерпретатора с помощью "perl_destruct" и освободить его с помощью "perl_free".

По историческим причинам ненулевое возвращаемое значение также пытается быть подходящим значением для передачи в функцию C-библиотеки exit (или для возврата из main), в качестве кода завершения, указывающего на характер завершения программы. Однако это не портативно из-за различий в соглашениях о кодах завершения. Пытается вернуть код завершения, требуемый операционной системой хоста, но поскольку он ограничен ненулевым значением, не всегда возможно указать каждый тип завершения. Он надежен только в Unix, где нулевой код завершения может быть дополнен установленным битом, который будет проигнорирован. В любом случае, эта функция не является правильным местом для получения кода завершения: его следует получить из "perl_destruct".

int  perl_run(PerlInterpreter *my_perl)
PERL_SET_CONTEXT

Описание в perlguts.

void  PERL_SET_CONTEXT(PerlInterpreter* i)
PERL_SYS_INIT
PERL_SYS_INIT3

Эти функции обеспечивают настройку среды выполнения C, специфичную для системы, необходимую для запуска интерпретаторов Perl. Должна быть использована только одна функция, и она должна вызываться только один раз до создания любых интерпретаторов Perl.

Они различаются тем, что PERL_SYS_INIT3 также инициализирует env.

void  PERL_SYS_INIT (int *argc, char*** argv)
void  PERL_SYS_INIT3(int *argc, char*** argv, char*** env)
PERL_SYS_TERM

Обеспечивает очистку среды выполнения C, специфичную для системы, после запуска интерпретаторов Perl. Эта функция должна вызываться только один раз после освобождения всех оставшихся интерпретаторов Perl.

void  PERL_SYS_TERM()
PL_exit_flags

Содержит флаги, контролирующие поведение perl при выходе (exit):

  • PERL_EXIT_DESTRUCT_END

    Если установлен, блоки END выполняются при уничтожении интерпретатора. Это обычно устанавливается самим perl после создания интерпретатора.

  • PERL_EXIT_ABORT

    Вызов abort() при выходе. Это используется внутри perl для прерывания, если exit вызывается во время обработки exit.

  • PERL_EXIT_WARN

    Предупреждение при выходе.

  • PERL_EXIT_EXPECTED

    Устанавливается оператором "exit" in perlfunc.

U8  PL_exit_flags
PL_origalen

Описание в perlembed.

PL_perl_destruct_level

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

Возможные значения:

  • 0 - нет

  • 1 - полная

  • 2 или больше - полная с проверками.

Если $ENV{PERL_DESTRUCT_LEVEL} установлено на целое число, большее, чем значение PL_perl_destruct_level, используется его значение.

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

signed char  PL_perl_destruct_level
ptr_table_fetch

Ищет sv в таблице сопоставления указателей tbl, возвращая его значение или NULL, если не найдено.

void *  ptr_table_fetch(PTR_TBL_t * const tbl,
                        const void * const sv)
ptr_table_free

Очистка и освобождение таблицы указателей

void  ptr_table_free(PTR_TBL_t * const tbl)
ptr_table_new

Создание новой таблицы сопоставления указателей

PTR_TBL_t *  ptr_table_new()
ptr_table_split

Удвоение размера корзины хэша существующей таблицы указателей

void  ptr_table_split(PTR_TBL_t * const tbl)
ptr_table_store

Добавление новой записи в таблицу сопоставления указателей tbl. В терминах хэша, oldsv является ключом; Cnewsv> — значение.

Названия "old" и "new" относятся к типичному использованию ptr_tables в ядре при клонировании потоков.

void  ptr_table_store(PTR_TBL_t * const tbl,
                      const void * const oldsv,
                      void * const newsv)
END_OF_DOCUMENT_MARKER
require_pv

Указывает Perl на require файл, имя которого задано в строковом аргументе. Это аналогично Perl-коду eval "require '$file'". Реализация даже такая; следует использовать load_module вместо этого.

ПРИМЕЧАНИЕ: форма perl_require_pv() устарела.

void  require_pv(const char *pv)
vload_module

Подобно "load_module", но аргументы представляют собой инкапсулированный список аргументов.

void  vload_module(U32 flags, SV *name, SV *ver, va_list *args)

Ошибка

sv_string_from_errnum

Генерирует строку сообщения об ошибке ОС и возвращает её как SV. errnum должно быть значением, которое errno может принять, определяя тип ошибки.

Если tgtsv не является нулевым указателем, то строка будет записана в этот SV (перезапишет существующее содержимое), и он будет возвращён. Если tgtsv является нулевым указателем, то строка будет записана в новый временный SV, который будет возвращён.

Сообщение будет взято из того языка, который использовал бы $!, и будет закодировано в SV тем способом, который использовал бы $!. Подробности этого процесса могут быть изменены в будущем. В настоящее время сообщение по умолчанию берется из C-языка (обычно это английское сообщение), а из выбранного языка – в рамках использования pragmy use locale. Выполняется попытка декодирования сообщения из кодировки символов языка, но оно будет декодировано либо как UTF-8, либо как ISO-8859-1. Оно всегда корректно декодируется в UTF-8-языке, обычно в ISO-8859-1-языке и никогда не декодируется в других языках.

SV всегда возвращается, содержащий фактическую строку и без других установленных битов OK. В отличие от $!, сообщение возвращается даже для errnum нуля (что означает успех), и если нет доступного полезного сообщения, то возвращается бесполезная строка (в настоящее время пустая).

SV *  sv_string_from_errnum(int errnum, SV *tgtsv)

Обработка исключений (простые) макросы

dXCPT

Настраивает необходимые локальные переменные для обработки исключений. См. "Обработка исключений" в perlguts.

dXCPT;
JMPENV_JUMP

Описано в perlinterp.

void  JMPENV_JUMP(int v)
JMPENV_PUSH

Описано в perlinterp.

void  JMPENV_PUSH(int v)
PL_restartop

Описано в perlinterp.

XCPT_CATCH

Вводит блок обработки исключений. См. "Обработка исключений" в perlguts.

XCPT_RETHROW

Перебрасывает ранее перехваченное исключение. См. "Обработка исключений" в perlguts.

XCPT_RETHROW;
XCPT_TRY_END

Завершает блок try. См. "Обработка исключений" в perlguts.

XCPT_TRY_START

Начинает блок try. См. "Обработка исключений" в perlguts.

Значения конфигурации файловой системы

Также см. "Список символов возможностей HAS_foo".

DIRNAMLEN

Если этот символ определён, C-программа понимает, что длина имён записей каталога задается в поле d_namlen. В противном случае, необходимо выполнить strlen() на поле d_name.

DOSUID

Если этот символ определён, C-программа должна проверять выполняемый скрипт на наличие битов setuid/setgid и пытаться эмулировать setuid/setgid на системах, где отключены скрипты setuid #!, потому что ядро не может сделать это безопасно. Задача разработчика пакета – обеспечить безопасную реализацию этой эмуляции. В частности, следует выполнить fstat на только что открытом скрипте, чтобы убедиться, что это действительно скрипт setuid/setgid, убедиться, что переданные аргументы точно соответствуют аргументам в строке #!, и не полагаться на какие-либо подпроцессы, которым необходимо передать имя файла, а не дескриптор файла выполняемого скрипта.

EOF_NONBLOCK

Если этот символ определён, C-программа понимает, что read() на дескрипторе файла в режиме без блокировки вернёт 0 в EOF, а не значение, хранящееся в RD_NODATA (-1 обычно в этом случае!).

FCNTL_CAN_LOCK

Если этот символ определён, то fcntl() может использоваться для блокировки файлов. Обычно определён на системах Unix. Может быть неопределён на VMS.

FFLUSH_ALL

Если этот символ определён, для сброса всех ожидающих выходов stdio необходимо пройтись по всем дескрипторам файлов stdio, хранящимся в массиве, и сбросить их с помощью fflush. Обратите внимание, что если fflushNULL определён, fflushall даже не будет проверяться и останется неопределённым.

FFLUSH_NULL

Если этот символ определён, то fflush(NULL) правильно сбрасывает все ожидающие выводы stdio без побочных эффектов. В частности, на некоторых платформах вызов fflush(NULL) *всё ещё* повреждает STDIN, если это труба.

FILE_base

Этот макрос используется для доступа к полю _base (или эквиваленту) структуры FILE, на которую указывает его аргумент. Этот макрос всегда будет определён, если USE_STDIO_BASE определён.

void *  FILE_base(FILE * f)
FILE_bufsiz

Этот макрос используется для определения количества байтов в буфере ввода-вывода, на который указывает поле _base (или эквивалент) структуры FILE, на которую указывает его аргумент. Этот макрос всегда будет определён, если USE_STDIO_BASE определён.

Size_t  FILE_bufsiz(FILE *f)
FILE_cnt

Этот макрос используется для доступа к полю _cnt (или эквиваленту) структуры FILE, на которую указывает его аргумент. Этот макрос всегда будет определён, если USE_STDIO_PTR определён.

Size_t  FILE_cnt(FILE * f)
FILE_ptr

Этот макрос используется для доступа к полю _ptr (или эквиваленту) структуры FILE, на которую указывает его аргумент. Этот макрос всегда будет определён, если USE_STDIO_PTR определён.

void *  FILE_ptr(FILE * f)
FLEXFILENAMES

Если этот символ определён, система поддерживает имена файлов длиннее 14 символов.

HAS_DIR_DD_FD

Если этот символ определён, структура потока каталога DIR содержит переменную-член под названием dd_fd.

HAS_DUP2

Если этот символ определён, доступна процедура dup2 для дублирования дескрипторов файлов.

HAS_DUP3

Если этот символ определён, доступна процедура dup3 для дублирования дескрипторов файлов.

HAS_FAST_STDIO

Если этот символ определён, доступна функция "быстрое stdio" для непосредственной работы с буферами stdio.

HAS_FCHDIR

Если этот символ определён, доступна процедура fchdir для изменения каталога с помощью дескриптора файла.

HAS_FCNTL

Если этот символ определён, C-программа понимает, что функция fcntl() существует.

HAS_FDCLOSE

Если этот символ определён, доступна процедура fdclose для освобождения структуры FILE без закрытия базового дескриптора файла. Эта функция появилась в FreeBSD 10.2.

HAS_FPATHCONF

Если этот символ определён, доступна функция pathconf() для определения ограничений и параметров, связанных с файловой системой, для заданного открытого дескриптора файла.

HAS_FPOS64_T

Этот символ будет определён, если компилятор C поддерживает fpos64_t.

HAS_FSTATFS

Если этот символ определён, доступна функция fstatfs для получения информации о файловой системе по дескриптору файла.

HAS_FSTATVFS

Если этот символ определён, доступна функция fstatvfs для получения информации о файловой системе по дескриптору файла.

HAS_GETFSSTAT

Если этот символ определён, доступна функция getfsstat для получения информации о файловых системах в целом.

HAS_GETMNT

Если этот символ определён, доступна функция getmnt для получения информации о монтировании файловой системы по имени файла.

HAS_GETMNTENT

Если этот символ определён, доступна функция getmntent для итерации по смонтированным файловым системам и получения информации о них.

HAS_HASMNTOPT

Если этот символ определён, доступна функция hasmntopt для запроса параметров монтирования файловых систем.

HAS_LSEEK_PROTO

Если этот символ определён, система предоставляет прототип для функции lseek(). В противном случае, программа должна предоставить его. Хорошее предположение:

extern off_t lseek(int, off_t, int);
HAS_MKDIR

Если этот символ определён, доступна функция mkdir для создания каталогов. В противном случае следует создать дочерний процесс для выполнения /bin/mkdir.

HAS_OFF64_T

Этот символ будет определён, если компилятор C поддерживает off64_t.

HAS_OPENAT

Этот символ определён, если доступна функция openat().

HAS_OPEN3

Эта константа указывает C-программе, что доступна форма с тремя аргументами функции open(2).

HAS_POLL

Этот символ, если определён, указывает, что процедура poll доступна для poll активных дескрипторов файлов. Пожалуйста, проверьте I_POLL и I_SYS_POLL, чтобы узнать, какой заголовок следует включить.

HAS_READDIR

Этот символ, если определён, указывает, что процедура readdir доступна для чтения записей каталога. Возможно, потребуется включить dirent.h. Смотрите "I_DIRENT".

HAS_READDIR64_R

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

HAS_REWINDDIR

Этот символ, если определён, указывает, что процедура rewinddir доступна. Возможно, потребуется включить dirent.h. Смотрите "I_DIRENT".

HAS_RMDIR

Этот символ, если определён, указывает, что процедура rmdir доступна для удаления каталогов. В противном случае следует создать новый процесс для выполнения /bin/rmdir.

HAS_SEEKDIR

Этот символ, если определён, указывает, что процедура seekdir доступна. Возможно, потребуется включить dirent.h. Смотрите "I_DIRENT".

HAS_SELECT

Этот символ, если определён, указывает, что процедура select доступна для select активных дескрипторов файлов. Если используется поле таймаута, может потребоваться включить sys/time.h.

HAS_SETVBUF

Этот символ, если определён, указывает, что процедура setvbuf доступна для изменения буферизации открытого потока stdio до буферизации по строкам.

HAS_STDIO_STREAM_ARRAY

Этот символ, если определён, указывает, что существует массив, хранящий потоки stdio.

HAS_STRUCT_FS_DATA

Этот символ, если определён, указывает, что процедура struct fs_data для выполнения statfs() поддерживается.

HAS_STRUCT_STATFS

Этот символ, если определён, указывает, что процедура struct statfs для выполнения statfs() поддерживается.

HAS_STRUCT_STATFS_F_FLAGS

Этот символ, если определён, указывает, что структура struct statfs содержит член f_flags, содержащий флаги монтирования файловой системы, содержащей файл. Такой тип struct statfs происходит из sys/mount.h (BSD 4.3), а не из sys/statfs.h (SYSV). Более старые реализации (например, Ultrix) не имеют statfs() и struct statfs, у них есть ustat() и getmnt() с struct ustat и struct fs_data.

HAS_TELLDIR

Этот символ, если определён, указывает, что процедура telldir доступна. Возможно, потребуется включить dirent.h. Смотрите "I_DIRENT".

HAS_USTAT

Этот символ, если определён, указывает, что системный вызов ustat доступен для запроса статистических данных файловой системы dev_t.

I_FCNTL

Эта константа указывает C-программе включить fcntl.h.

#ifdef I_FCNTL
    #include <fcntl.h>
#endif
I_SYS_DIR

Этот символ, если определён, указывает C-программе включить sys/dir.h.

#ifdef I_SYS_DIR
    #include <sys_dir.h>
#endif
I_SYS_FILE

Этот символ, если определён, указывает C-программе включить sys/file.h, чтобы получить определение R_OK и связанных функций.

#ifdef I_SYS_FILE
    #include <sys_file.h>
#endif
I_SYS_NDIR

Этот символ, если определён, указывает C-программе включить sys/ndir.h.

#ifdef I_SYS_NDIR
    #include <sys_ndir.h>
#endif
I_SYS_STATFS

Этот символ, если определён, указывает, что sys/statfs.h существует.

#ifdef I_SYS_STATFS
    #include <sys_statfs.h>
#endif
LSEEKSIZE

Этот символ содержит количество байт, используемых Off_t.

RD_NODATA

Этот символ содержит код возврата read() при отсутствии данных на неблокирующем дескрипторе файла. Будьте внимательны! Если EOF_NONBLOCK не определён, то нельзя отличить отсутствие данных от EOF путём выдачи read(). Вам нужно найти другой способ узнать наверняка!

READDIR64_R_PROTO

Этот символ кодирует прототип readdir64_r . Он равен нулю, если d_readdir64_r не определено, и одному из макросов REENTRANT_PROTO_T_ABC из reentr.h, если d_readdir64_r определено.

STDCHAR

Этот символ определён как тип char, используемый в stdio.h. Он имеет значения "unsigned char" или "char".

STDIO_CNT_LVALUE

Этот символ определён, если макрос FILE_cnt может быть использован как lvalue.

STDIO_PTR_LVAL_NOCHANGE_CNT

Этот символ определён, если использование макроса FILE_ptr как lvalue для увеличения указателя на n оставляет значение File_cnt(fp) неизменным.

STDIO_PTR_LVAL_SETS_CNT

Этот символ определён, если использование макроса FILE_ptr как lvalue для увеличения указателя на n приводит к уменьшению значения File_cnt(fp) на n.

STDIO_PTR_LVALUE

Этот символ определён, если макрос FILE_ptr может быть использован как lvalue.

STDIO_STREAM_ARRAY

Этот символ указывает имя массива, хранящего потоки stdio. Типичные значения включают _iob, __iob, и __sF.

ST_INO_SIGN

Этот символ содержит признак знакового типа struct stat's st_ino. 1 для беззнакового, -1 для знакового.

ST_INO_SIZE

Эта переменная содержит размер struct stat's st_ino в байтах.

VAL_EAGAIN

Этот символ содержит код ошибки errno, устанавливаемый read() при отсутствии данных на неблокирующем дескрипторе файла.

VAL_O_NONBLOCK

Этот символ используется при open() или fcntl(F_SETFL) для включения неблокирующего ввода-вывода для дескриптора файла. Обратите внимание, что нет способа вернуться к блокирующему режиму таким способом. Если вы хотите переключаться между блокирующим и неблокирующим режимом, используйте вызов ioctl(FIOSNBIO), но он не поддерживается всеми устройствами.

VOID_CLOSEDIR

Этот символ, если определён, указывает, что процедура closedir() не возвращает значение.

Плавающая точка

Также в "Список символов возможностей HAS_foo" перечислены возможности, которые не указаны в данном разделе. Например, HAS_ASINH, для функции гиперболического синуса.

CASTFLAGS

Этот символ содержит флаги, которые указывают, с какими трудностями сталкивается компилятор при приведении нестандартных значений с плавающей точкой к unsigned long:

0 = ok
1 = couldn't cast < 0
2 = couldn't cast >= 0x80000000
4 = couldn't cast in argument expression list
CASTNEGFLOAT

Этот символ определён, если компилятор C может преобразовывать отрицательные числа к unsigned long, int и short.

DOUBLE_HAS_INF

Этот символ, если определён, указывает, что тип double имеет бесконечность.

DOUBLE_HAS_NAN

Этот символ, если определён, указывает, что тип double имеет значение "не число" (NaN).

DOUBLE_HAS_NEGATIVE_ZERO

Этот символ, если определён, указывает, что тип double имеет negative_zero.

DOUBLE_HAS_SUBNORMALS

Этот символ, если определён, указывает, что тип double имеет субнормали (денормали).

DOUBLEINFBYTES

Этот символ, если определён, представляет собой список шестнадцатеричных байтов через запятую для бесконечности с двойной точностью.

DOUBLEKIND

DOUBLEKIND будет одним из DOUBLE_IS_IEEE_754_32_BIT_LITTLE_ENDIAN DOUBLE_IS_IEEE_754_32_BIT_BIG_ENDIAN DOUBLE_IS_IEEE_754_64_BIT_LITTLE_ENDIAN DOUBLE_IS_IEEE_754_64_BIT_BIG_ENDIAN DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_LE_BE DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_BE_LE DOUBLE_IS_VAX_F_FLOAT DOUBLE_IS_VAX_D_FLOAT DOUBLE_IS_VAX_G_FLOAT DOUBLE_IS_IBM_SINGLE_32_BIT DOUBLE_IS_IBM_DOUBLE_64_BIT DOUBLE_IS_CRAY_SINGLE_64_BIT DOUBLE_IS_UNKNOWN_FORMAT

DOUBLEMANTBITS

Этот символ, если определён, указывает количество битов мантиссы в формате с плавающей точкой двойной точности. Обратите внимание, что это обычно DBL_MANT_DIG минус один, так как в стандартных форматах IEEE 754 DBL_MANT_DIG включает неявный бит, который фактически не существует.

DOUBLENANBYTES

Этот символ, если определён, представляет собой список шестнадцатеричных байтов (0xHH) через запятую для не числа (NaN) с двойной точностью.

DOUBLESIZE

Этот символ содержит размер типа double, чтобы препроцессор C мог принимать решения, основанные на нём.

DOUBLE_STYLE_CRAY

Этот символ, если определён, указывает, что тип double — 64-битный формат вычислительной системы Cray.

DOUBLE_STYLE_IBM

Этот символ, если определён, указывает, что тип double — 64-битный формат вычислительной системы IBM.

DOUBLE_STYLE_IEEE

Этот символ, если определён, указывает, что тип double — 64-битный формат IEEE 754.

DOUBLE_STYLE_VAX

Этот символ, если определён, указывает, что тип double — 64-битный формат VAX D или G.

HAS_ATOLF

Этот символ, если определён, указывает, что процедура atolf доступна для преобразования строк в long double.

HAS_CLASS

Этот символ, если определён, указывает, что процедура class доступна для классификации чисел с плавающей точкой. Доступна, например, в AIX. Возвращаемые значения определены в float.h и являются:

FP_PLUS_NORM    Positive normalized, nonzero
FP_MINUS_NORM   Negative normalized, nonzero
FP_PLUS_DENORM  Positive denormalized, nonzero
FP_MINUS_DENORM Negative denormalized, nonzero
FP_PLUS_ZERO    +0.0
FP_MINUS_ZERO   -0.0
FP_PLUS_INF     +INF
FP_MINUS_INF    -INF
FP_NANS         Signaling Not a Number (NaNS)
FP_NANQ         Quiet Not a Number (NaNQ)
HAS_FINITE

Этот символ, если определён, указывает, что процедура finite доступна для проверки, является ли двойное значение finite (не бесконечность, не NaN).

HAS_FINITEL

Этот символ, если определён, указывает, что процедура finitel доступна для проверки, является ли длинное двойное значение конечным (не бесконечность, не NaN).

HAS_FPCLASS

Этот символ, если определён, указывает, что процедура fpclass доступна для классификации двойных значений. Доступна, например, в Solaris/SVR4. Возвращаемые значения определены в ieeefp.h и являются:

FP_SNAN         signaling NaN
FP_QNAN         quiet NaN
FP_NINF         negative infinity
FP_PINF         positive infinity
FP_NDENORM      negative denormalized non-zero
FP_PDENORM      positive denormalized non-zero
FP_NZERO        negative zero
FP_PZERO        positive zero
FP_NNORM        negative normalized non-zero
FP_PNORM        positive normalized non-zero
HAS_FP_CLASS

Этот символ, если определён, указывает, что процедура fp_class доступна для классификации двойных значений. Доступна, например, в Digital UNIX. Возвращаемые значения определены в math.h и являются:

FP_SNAN           Signaling NaN (Not-a-Number)
FP_QNAN           Quiet NaN (Not-a-Number)
FP_POS_INF        +infinity
FP_NEG_INF        -infinity
FP_POS_NORM       Positive normalized
FP_NEG_NORM       Negative normalized
FP_POS_DENORM     Positive denormalized
FP_NEG_DENORM     Negative denormalized
FP_POS_ZERO       +0.0 (positive zero)
FP_NEG_ZERO       -0.0 (negative zero)
HAS_FPCLASSIFY

Этот символ, если определён, указывает, что процедура fpclassify доступна для классификации двойных значений. Доступна, например, в HP-UX. Возвращаемые значения определены в math.h и являются:

FP_NORMAL     Normalized
FP_ZERO       Zero
FP_INFINITE   Infinity
FP_SUBNORMAL  Denormalized
FP_NAN        NaN
HAS_FP_CLASSIFY

Этот символ, если определён, указывает, что процедура fp_classify доступна для классификации двойных значений. Значения определены в math.h

FP_NORMAL     Normalized
FP_ZERO       Zero
FP_INFINITE   Infinity
FP_SUBNORMAL  Denormalized
FP_NAN        NaN
HAS_FPCLASSL

Этот символ, если определён, указывает, что процедура fpclassl доступна для классификации длинных двойных значений. Доступна, например, в IRIX. Возвращаемые значения определены в ieeefp.h и являются:

FP_SNAN         signaling NaN
FP_QNAN         quiet NaN
FP_NINF         negative infinity
FP_PINF         positive infinity
FP_NDENORM      negative denormalized non-zero
FP_PDENORM      positive denormalized non-zero
FP_NZERO        negative zero
FP_PZERO        positive zero
FP_NNORM        negative normalized non-zero
FP_PNORM        positive normalized non-zero
HAS_FP_CLASSL

Этот символ, если определён, указывает, что процедура fp_classl доступна для классификации длинных двойных значений. Доступна, например, в Digital UNIX. Возможные значения см. HAS_FP_CLASS.

HAS_FPGETROUND

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

HAS_FREXPL

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

HAS_ILOGB

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

HAS_ISFINITE

Этот символ, если определён, указывает, что процедура isfinite доступна для проверки, является ли двойное значение конечным (не бесконечность, не NaN).

HAS_ISFINITEL

Этот символ, если определён, указывает, что процедура isfinitel доступна для проверки, является ли длинное двойное значение конечным. (не бесконечность, не NaN).

HAS_ISINF

Этот символ, если определён, указывает, что процедура isinf доступна для проверки, является ли двойное значение бесконечностью.

HAS_ISINFL

Этот символ, если определён, указывает, что процедура isinfl доступна для проверки, является ли длинное двойное значение бесконечностью.

HAS_ISNAN

Этот символ, если определён, указывает, что процедура isnan доступна для проверки, является ли двойное значение NaN.

HAS_ISNANL

Этот символ, если определён, указывает, что процедура isnanl доступна для проверки, является ли длинное двойное значение NaN.

HAS_ISNORMAL

Этот символ, если определён, указывает, что процедура isnormal доступна для проверки, является ли двойное значение нормальным (не нулевое, нормализованное).

HAS_J0L

Этот символ, если определён, указывает C программе, что функция j0l() доступна для функций Бесселя первого рода нулевого порядка для длинных двойных значений.

HAS_J0

Этот символ, если определён, указывает C программе, что функция j0() доступна для функций Бесселя первого рода нулевого порядка для двойных значений.

HAS_LDBL_DIG

Этот символ, если определён, указывает, что в float.h или limits.h этой системы определён символ LDBL_DIG, который представляет количество значащих цифр в числе с длинной двойной точностью. В отличие от DBL_DIG, нет хорошего предположения для LDBL_DIG, если он не определён.

HAS_LDEXPL

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

HAS_LLRINT

Этот символ, если определён, указывает, что процедура llrint доступна для возвращения длинного целого значения, наиболее близкого к двойному значению (согласно текущему режиму округления).

HAS_LLRINTL

Этот символ, если определён, указывает, что процедура llrintl доступна для возвращения длинного целого значения, наиболее близкого к длинному двойному значению (согласно текущему режиму округления).

HAS_LLROUNDL

Этот символ, если определён, указывает, что процедура llroundl доступна для возвращения ближайшего длинного целого значения, удалённого от нуля, аргумента длинного двойного значения.

HAS_LONG_DOUBLE

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

HAS_LRINT

Этот символ, если определён, указывает, что процедура lrint доступна для возвращения целого значения, ближайшего к двойному значению (согласно текущему режиму округления).

HAS_LRINTL

Этот символ, если определён, указывает, что процедура lrintl доступна для возвращения целого значения, ближайшего к длинному двойному значению (согласно текущему режиму округления).

HAS_LROUNDL

Этот символ, если определён, указывает, что процедура lroundl доступна для возвращения ближайшего целого значения, удалённого от нуля, аргумента длинного двойного значения.

HAS_MODFL

Этот символ, если определён, указывает, что процедура modfl доступна для разделения длинного двойного значения x на дробную часть f и целую часть i такую, что |f| < 1.0 и (f + i) = x.

HAS_NAN

Этот символ, если определён, указывает, что процедура nan доступна для генерации NaN.

HAS_NEXTTOWARD

Этот символ, если определён, указывает, что процедура nexttoward доступна для возвращения следующего машинного представимого длинного двойного значения от x в направлении y.

HAS_REMAINDER

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

HAS_SCALBN

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

HAS_SIGNBIT

Этот символ, если определён, указывает, что процедура signbit доступна для проверки, установлен ли бит знака данного числа. Это должно включать правильную проверку -0.0. Это будет установлено только в том случае, если процедура signbit() безопасна для использования с типом NV, используемым внутри perl. Пользователи должны вызывать Perl_signbit(), которое будет определено как системная функция или макрос signbit(), если этот символ определён.

HAS_SQRTL

Этот символ, если определён, указывает, что процедура sqrtl доступна для вычисления квадратных корней длинных двойных значений.

HAS_STRTOD_L

Этот символ, если определён, указывает, что процедура strtod_l доступна для преобразования строк в длинные двойные значения.

HAS_STRTOLD

Этот символ, если определён, указывает, что процедура strtold доступна для преобразования строк в длинные двойные значения.

HAS_STRTOLD_L

Этот символ, если определён, указывает, что процедура strtold_l доступна для преобразования строк в длинные двойные значения.

HAS_TRUNC

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

HAS_UNORDERED

Этот символ, если определён, указывает, что процедура unordered доступна для проверки, являются ли два двойных значения unordered (фактически: является ли одно из них NaN).

I_FENV

Этот символ, если определён, указывает C программе, что она должна включить fenv.h, чтобы получить определения среды с плавающей точкой.

#ifdef I_FENV
    #include <fenv.h>
#endif
I_QUADMATH

Этот символ, если определён, указывает, что quadmath.h существует и должен быть включён.

#ifdef I_QUADMATH
    #include <quadmath.h>
#endif
LONGDBLINFBYTES

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

LONGDBLMANTBITS

Этот символ, если определён, указывает, сколько бит мантиссы присутствует в формате чисел с плавающей точкой длинной двойной точности. Обратите внимание, что это может быть LDBL_MANT_DIG минус один, поскольку LDBL_MANT_DIG может включать IEEE неявный бит 754. Обычный длинный двойной тип данных x86-стиля 80 бит не имеет неявного бита.

LONGDBLNANBYTES

Этот символ, если определён, представляет собой список шестнадцатеричных байтов (0xHH) через запятую для числа не-число (NaN) длинной двойной точности.

LONG_DOUBLEKIND

LONG_DOUBLEKIND будет одним из LONG_DOUBLE_IS_DOUBLE LONG_DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN LONG_DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN LONG_DOUBLE_IS_X86_80_BIT_LITTLE_ENDIAN LONG_DOUBLE_IS_X86_80_BIT_BIG_ENDIAN LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_LE LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_BE LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_BE LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_LE LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LITTLE_ENDIAN LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BIG_ENDIAN LONG_DOUBLE_IS_VAX_H_FLOAT LONG_DOUBLE_IS_UNKNOWN_FORMAT. Он определён только в том случае, если система поддерживает длинные двойные значения.

LONG_DOUBLESIZE

Этот символ содержит размер long double, чтобы препроцессор C мог принимать решения на его основе. Он определяется только если система поддерживает long double. Обратите внимание, что это sizeof(long double), который может включать неиспользуемые байты.

LONG_DOUBLE_STYLE_IEEE

Этот символ, если определён, указывает, что long double является одним из IEEE long double стандарта 754: LONG_DOUBLE_STYLE_IEEE_STD, LONG_DOUBLE_STYLE_IEEE_EXTENDED, LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE.

LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE

Этот символ, если определён, указывает, что long double является 128-битным double-double.

LONG_DOUBLE_STYLE_IEEE_EXTENDED

Этот символ, если определён, указывает, что long double является 80-битным IEEE стандарта 754. Обратите внимание, что, несмотря на «extended», он меньше, чем «std», поскольку это расширение двойной точности.

LONG_DOUBLE_STYLE_IEEE_STD

Этот символ, если определён, указывает, что long double является 128-битным IEEE стандарта 754.

LONG_DOUBLE_STYLE_VAX

Этот символ, если определён, указывает, что long double имеет формат 128-битный VAX H.

NV

Описание в perlguts.

NVMANTBITS

Этот символ, если определён, указывает количество битов мантиссы (без учёта неявного бита) в Perl NV. Это зависит от выбранного типа с плавающей точкой.

NV_OVERFLOWS_INTEGERS_AT

Этот символ содержит максимальное целочисленное значение, которое могут содержать NV. Это значение + 1.0 не может быть точно представлено. Оно выражается как константное выражение с плавающей точкой, чтобы уменьшить вероятность проблем с преобразованием десятичной/двоичной систем. Если значение определить невозможно, то возвращается 0.

NV_PRESERVES_UV

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

NV_PRESERVES_UV_BITS

Этот символ содержит количество битов, которое переменная типа NVTYPE может сохранить от переменной типа UVTYPE.

NVSIZE

Этот символ содержит sizeof(NV). Обратите внимание, что некоторые форматы чисел с плавающей точкой имеют неиспользуемые байты. Наиболее заметным примером является 80-битная расширенная точность x86*, которая имеет размер 12 и 16 байт (для 32- и 64-разрядных платформ соответственно), но использует только 10 байт. Perl, скомпилированный с -Duselongdouble на x86*, работает именно так.

NVTYPE

Этот символ определяет тип C, используемый для NV Perl.

NV_ZERO_IS_ALLBITS_ZERO

Этот символ, если определён, указывает, что переменная типа NVTYPE хранит 0.0 в памяти как все биты ноль.

Настройка по умолчанию

Этот раздел содержит информацию о настройке, которая не найдена в других разделах документа. В конце перечислены #defines, названия которых достаточно для понимания их назначения, и список #define, которые показывают, нужно ли вам #include файлы для получения соответствующей функциональности.

ASCIIish

Символ препроцессора, который определён, если система основана на ASCII; этот символ не будет определён на "EBCDIC" платформах.

#ifdef  ASCIIish
BYTEORDER

Этот символ содержит шестнадцатеричную константу, определённую в byteorder, в UV, т.е. 0x1234 или 0x4321 или 0x12345678 и т.д... Если компилятор поддерживает кросс-компиляцию или двоичные файлы для нескольких архитектур, используйте макросы, определённые в компиляторе, для определения порядка байтов.

CHARBITS

Этот символ содержит размер char, чтобы препроцессор C мог принимать решения на его основе.

DB_VERSION_MAJOR_CFG

Этот символ, если определён, задаёт номер основной версии Berkeley DB, найденной в заголовке db.h при настройке Perl.

DB_VERSION_MINOR_CFG

Этот символ, если определён, задаёт номер дополнительной версии Berkeley DB, найденной в заголовке db.h при настройке Perl. Для версии DB 1 он всегда равен 0.

DB_VERSION_PATCH_CFG

Этот символ, если определён, задаёт номер дополнительной версии Berkeley DB, найденной в заголовке db.h при настройке Perl. Для версии DB 1 он всегда равен 0.

DEFAULT_INC_EXCLUDES_DOT

Этот символ, если определён, удаляет устаревшее поведение по умолчанию, включающее «.» в конце @INC.

DLSYM_NEEDS_UNDERSCORE

Этот символ, если определён, указывает на необходимость добавления нижнего подчёркивания к имени символа перед вызовом dlsym(). Это имеет смысл только если используется dlsym, что мы предполагаем, если используется dl_dlopen.xs.

EBCDIC

Этот символ, если определён, указывает, что система использует кодировку EBCDIC.

HAS_CSH

Этот символ, если определён, указывает, что существует оболочка C-shell.

HAS_GETHOSTNAME

Этот символ, если определён, указывает, что C-программа может использовать функцию gethostname() для получения имени хоста. См. также "HAS_UNAME" и "PHOSTNAME".

HAS_GNULIBC

Этот символ, если определён, указывает C-программе, что используется библиотека C GNU. Более надёжная проверка — использование символов __GLIBC__ и __GLIBC_MINOR__, предоставляемых glibc.

HAS_LGAMMA

Этот символ, если определён, указывает, что функция lgamma для вычисления логарифма гамма-функции доступна. См. также "HAS_TGAMMA" и "HAS_LGAMMA_R".

HAS_LGAMMA_R

Этот символ, если определён, указывает, что функция lgamma_r для вычисления логарифма гамма-функции доступна без использования глобальной переменной signgam.

HAS_NON_INT_BITFIELDS

Этот символ, если определён, указывает, что компилятор C без ошибок или предупреждений принимает битовые поля, объявленные с размерами, отличными от простого 'int'; например, 'unsigned char' принимается.

HAS_PRCTL_SET_NAME

Этот символ, если определён, указывает, что функция prctl доступна для установки имени процесса и поддерживает PR_SET_NAME.

HAS_PROCSELFEXE

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

HAS_PSEUDOFORK

Этот символ, если определён, указывает, что доступна эмуляция функции fork.

HAS_REGCOMP

Этот символ, если определён, указывает, что функция regcomp() доступна для выполнения сопоставления с шаблоном регулярного выражения (обычно на системах, соответствующих стандарту POSIX.2).

HAS_SETPGID

Этот символ, если определён, указывает, что функция setpgid(pid, gpid) доступна для установки идентификатора группы процесса.

HAS_SIGSETJMP

Эта переменная указывает C-программе, что функция sigsetjmp() доступна для сохранения регистров и среды стека вызывающего процесса для последующего использования siglongjmp(), а также для опционального сохранения маски сигналов процесса. См. "Sigjmp_buf", "Sigsetjmp", и "Siglongjmp".

HAS_STRUCT_CMSGHDR

Этот символ, если определён, указывает, что struct cmsghdr поддерживается.

HAS_STRUCT_MSGHDR

Этот символ, если определён, указывает, что struct msghdr поддерживается.

HAS_TGAMMA

Этот символ, если определён, указывает, что функция tgamma для вычисления гамма-функции доступна. См. также "HAS_LGAMMA".

HAS_UNAME

Этот символ, если определён, указывает, что C-программа может использовать функцию uname() для получения имени хоста. См. также "HAS_GETHOSTNAME" и "PHOSTNAME".

HAS_UNION_SEMUN

Этот символ, если определён, указывает, что union semun определено с помощью sys/sem.h. В противном случае, коду пользователя, вероятно, нужно определить его как:

union semun {
int val;
struct semid_ds *buf;
unsigned short *array;
}
I_DIRENT

Этот символ, если определён, указывает C-программе, что она должна включить dirent.h. Использование этого символа также приводит к определению Direntry_t define, которое в итоге будет 'struct dirent' или 'struct direct', в зависимости от доступности dirent.h.

#ifdef I_DIRENT
    #include <dirent.h>
#endif
I_POLL

Этот символ, если определён, указывает, что poll.h существует и должно быть включено. (см. также "HAS_POLL")

#ifdef I_POLL
    #include <poll.h>
#endif
I_SYS_RESOURCE

Этот символ, если определён, указывает C-программе, что она должна включить sys/resource.h.

#ifdef I_SYS_RESOURCE
    #include <sys_resource.h>
#endif
LIBM_LIB_VERSION

Этот символ, если определён, указывает, что libm экспортирует _LIB_VERSION и что math.h определяет перечисление для его управления.

NEED_VA_COPY

Этот символ, если определён, указывает, что система хранит тип переменной аргумента va_list в формате, который нельзя просто скопировать присваиванием, поэтому при необходимости копирования требуется использовать другие средства. Поскольку системы различаются в предоставлении (или отсутствии) механизмов копирования, handy.h определяет независимый от платформы макрос Perl_va_copy(src, dst) для выполнения этой задачи.

OSNAME

Этот символ содержит имя операционной системы, определённое Configure. Не следует слишком сильно полагаться на него; тесты функций Configure обычно более надёжны.

OSVERS

Этот символ содержит версию операционной системы, определённую Configure. Не следует слишком сильно полагаться на него; тесты функций Configure обычно более надёжны.

PERL_USE_GCC_BRACE_GROUPS

Это значение препроцессора C, которое, если определено, указывает, что разрешено использовать расширение GCC brace groups. Однако использование этого расширения НЕ РЕКОМЕНДУЕТСЯ. Используйте функцию static inline вместо неё.

Расширение в формате

({ statement ... })

преобразует блок, состоящий из statement ..., в выражение со значением, в отличие от обычных блоков языка C. Это может предоставить возможности оптимизации, НО, если вы не уверены, что этот код никогда не будет скомпилирован без этого расширения и не будет запрещён, вам нужно указать альтернативу. Таким образом, необходимо поддерживать два пути кода, которые могут разойтись. Все эти проблемы решаются с помощью функции static inline вместо неё.

Perl можно настроить так, чтобы не использовать эту функцию, передав параметр -Accflags=-DPERL_GCC_BRACE_GROUPS_FORBIDDEN в Configure.

#ifdef  PERL_USE_GCC_BRACE_GROUPS
PHOSTNAME

Этот символ, если определён, указывает команду, которая должна быть передана в процедуру popen() для получения имени хоста. Также см. "HAS_GETHOSTNAME" и "HAS_UNAME". Обратите внимание, что команда использует полный путь, что безопасно даже если используется процессом с привилегиями суперпользователя.

PROCSELFEXE_PATH

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

PTRSIZE

Этот символ содержит размер указателя, чтобы препроцессор C мог принимать решения, основанные на нём. Он будет sizeof(void *), если компилятор поддерживает (void *); в противном случае он будет sizeof(char *).

RANDBITS

Этот символ указывает, сколько бит генерирует функция, используемая для генерации нормализованных случайных чисел. Значения включают 15, 16, 31 и 48.

SELECT_MIN_BITS

Этот символ содержит минимальное количество бит, обрабатываемых select. То есть, если вы делаете select(n, ...), сколько бит как минимум будет очищено в масках, если обнаружена какая-либо активность. Обычно это либо n, либо 32*ceil(n/32), особенно многие системы little-endian используют последнее. Это полезно только если у вас select(), естественно.

SETUID_SCRIPTS_ARE_SECURE_NOW

Этот символ, если определён, указывает, что в данном ядре отсутствует ошибка, которая препятствует обеспечению безопасности скриптов setuid.

ST_DEV_SIGN

Этот символ содержит знак struct stat's st_dev. 1 для беззнакового, -1 для знакового.

ST_DEV_SIZE

Эта переменная содержит размер struct stat's st_dev в байтах.

Список символов возможностей HAS_foo

Это список символов, которые не появляются в других разделах этого документа и указывают, обладает ли текущая платформа определённой возможностью. Их имена все начинаются с HAS_. Здесь перечислены только те символы, чья возможность непосредственно выводится из имени. Все остальные имеют расшифровку в других разделах этого документа. Этот (относительно) компактный список, потому что мы считаем, что расширение добавит мало или совсем не добавит ценности и займёт много места (потому что их очень много). Если вы считаете, что определённые из них следует расширить, отправьте письмо на адрес perl5-porters@perl.org.

Каждый символ здесь будет #defined только в том случае, если платформа обладает данной возможностью. Если вам нужна более подробная информация, см. соответствующую запись в config.h. Для удобства список разделен, так что те, которые указывают на наличие реентерабельной версии возможности, перечислены отдельно.

HAS_ACCEPT4, HAS_ACCESS, HAS_ACCESSX, HAS_ACOSH, HAS_AINTL, HAS_ALARM, HAS_ASINH, HAS_ATANH, HAS_ATOLL, HAS_CBRT, HAS_CHOWN, HAS_CHROOT, HAS_CHSIZE, HAS_CLEARENV, HAS_COPYSIGN, HAS_COPYSIGNL, HAS_CRYPT, HAS_CTERMID, HAS_CUSERID, HAS_DIRFD, HAS_DLADDR, HAS_DLERROR, HAS_EACCESS, HAS_ENDHOSTENT, HAS_ENDNETENT, HAS_ENDPROTOENT, HAS_ENDSERVENT, HAS_ERF, HAS_ERFC, HAS_EXPM1, HAS_EXP2, HAS_FCHMOD, HAS_FCHMODAT, HAS_FCHOWN, HAS_FDIM, HAS_FD_SET, HAS_FEGETROUND, HAS_FFS, HAS_FFSL, HAS_FGETPOS, HAS_FLOCK, HAS_FMA, HAS_FMAX, HAS_FMIN, HAS_FORK, HAS_FSEEKO, HAS_FSETPOS, HAS_FSYNC, HAS_FTELLO, HAS__FWALK, HAS_GAI_STRERROR, HAS_GETADDRINFO, HAS_GETCWD, HAS_GETESPWNAM, HAS_GETGROUPS, HAS_GETHOSTBYADDR, HAS_GETHOSTBYNAME, HAS_GETHOSTENT, HAS_GETLOGIN, HAS_GETNAMEINFO, HAS_GETNETBYADDR, HAS_GETNETBYNAME, HAS_GETNETENT, HAS_GETPAGESIZE, HAS_GETPGID, HAS_GETPGRP, HAS_GETPGRP2, HAS_GETPPID, HAS_GETPRIORITY, HAS_GETPROTOBYNAME, HAS_GETPROTOBYNUMBER, HAS_GETPROTOENT, HAS_GETPRPWNAM, HAS_GETSERVBYNAME, HAS_GETSERVBYPORT, HAS_GETSERVENT, HAS_GETSPNAM, HAS_HTONL, HAS_HTONS, HAS_HYPOT, HAS_ILOGBL, HAS_INET_ATON, HAS_INETNTOP, HAS_INETPTON, HAS_IP_MREQ, HAS_IP_MREQ_SOURCE, HAS_IPV6_MREQ, HAS_IPV6_MREQ_SOURCE, HAS_ISASCII, HAS_ISBLANK, HAS_ISLESS, HAS_KILLPG, HAS_LCHOWN, HAS_LINK, HAS_LINKAT, HAS_LLROUND, HAS_LOCKF, HAS_LOGB, HAS_LOG1P, HAS_LOG2, HAS_LROUND, HAS_LSTAT, HAS_MADVISE, HAS_MBLEN, HAS_MBRLEN, HAS_MBRTOWC, HAS_MBSTOWCS, HAS_MBTOWC, HAS_MEMMEM, HAS_MEMRCHR, HAS_MKDTEMP, HAS_MKFIFO, HAS_MKOSTEMP, HAS_MKSTEMP, HAS_MKSTEMPS, HAS_MMAP, HAS_MPROTECT, HAS_MSG, HAS_MSYNC, HAS_MUNMAP, HAS_NEARBYINT, HAS_NEXTAFTER, HAS_NICE, HAS_NTOHL, HAS_NTOHS, HAS_PATHCONF, HAS_PAUSE, HAS_PHOSTNAME, HAS_PIPE, HAS_PIPE2, HAS_PRCTL, HAS_PTRDIFF_T, HAS_READLINK, HAS_READV, HAS_RECVMSG, HAS_REMQUO, HAS_RENAME, HAS_RENAMEAT, HAS_RINT, HAS_ROUND, HAS_SCALBNL, HAS_SEM, HAS_SENDMSG, HAS_SETEGID, HAS_SETENV, HAS_SETEUID, HAS_SETGROUPS, HAS_SETHOSTENT, HAS_SETLINEBUF, HAS_SETNETENT, HAS_SETPGRP, HAS_SETPGRP2, HAS_SETPRIORITY, HAS_SETPROCTITLE, HAS_SETPROTOENT, HAS_SETREGID, HAS_SETRESGID, HAS_SETRESUID, HAS_SETREUID, HAS_SETRGID, HAS_SETRUID, HAS_SETSERVENT, HAS_SETSID, HAS_SHM, HAS_SIGACTION, HAS_SIGPROCMASK, HAS_SIN6_SCOPE_ID, HAS_SNPRINTF, HAS_STAT, HAS_STRCOLL, HAS_STRERROR_L, HAS_STRLCAT, HAS_STRLCPY, HAS_STRNLEN, HAS_STRTOD, HAS_STRTOL, HAS_STRTOLL, HAS_STRTOQ, HAS_STRTOUL, HAS_STRTOULL, HAS_STRTOUQ, HAS_STRXFRM, HAS_STRXFRM_L, HAS_SYMLINK, HAS_SYSCALL, HAS_SYSCONF, HAS_SYS_ERRLIST, HAS_SYSTEM, HAS_TCGETPGRP, HAS_TCSETPGRP, HAS_TOWLOWER, HAS_TOWUPPER, HAS_TRUNCATE, HAS_TRUNCL, HAS_UALARM, HAS_UMASK, HAS_UNLINKAT, HAS_UNSETENV, HAS_VFORK, HAS_VSNPRINTF, HAS_WAITPID, HAS_WAIT4, HAS_WCRTOMB, HAS_WCSCMP, HAS_WCSTOMBS, HAS_WCSXFRM, HAS_WCTOMB, HAS_WRITEV, HAS_CRYPT_R, HAS_CTERMID_R, HAS_DRAND48_R, HAS_ENDHOSTENT_R, HAS_ENDNETENT_R, HAS_ENDPROTOENT_R, HAS_ENDSERVENT_R, HAS_GETGRGID_R, HAS_GETGRNAM_R, HAS_GETHOSTBYADDR_R, HAS_GETHOSTBYNAME_R, HAS_GETHOSTENT_R, HAS_GETLOGIN_R, HAS_GETNETBYADDR_R, HAS_GETNETBYNAME_R, HAS_GETNETENT_R, HAS_GETPROTOBYNAME_R, HAS_GETPROTOBYNUMBER_R, HAS_GETPROTOENT_R, HAS_GETPWNAM_R, HAS_GETPWUID_R, HAS_GETSERVBYNAME_R, HAS_GETSERVBYPORT_R, HAS_GETSERVENT_R, HAS_GETSPNAM_R, HAS_RANDOM_R, HAS_READDIR_R, HAS_SETHOSTENT_R, HAS_SETNETENT_R, HAS_SETPROTOENT_R, HAS_SETSERVENT_R, HAS_SRANDOM_R, HAS_SRAND48_R, HAS_STRERROR_R, HAS_TMPNAM_R, HAS_TTYNAME_R, 

#ifdef HAS_STRNLEN
  use strnlen()
#else
  use an alternative implementation
#endif
, #ifdef HAS_STRNLEN use strnlen() #else use an alternative implementation #endif, #include, #include, #include, #define)

И, реентерабельные возможности:

HAS_CRYPT_R, HAS_CTERMID_R, HAS_DRAND48_R, HAS_ENDHOSTENT_R, HAS_ENDNETENT_R, HAS_ENDPROTOENT_R, HAS_ENDSERVENT_R, HAS_GETGRGID_R, HAS_GETGRNAM_R, HAS_GETHOSTBYADDR_R, HAS_GETHOSTBYNAME_R, HAS_GETHOSTENT_R, HAS_GETLOGIN_R, HAS_GETNETBYADDR_R, HAS_GETNETBYNAME_R, HAS_GETNETENT_R, HAS_GETPROTOBYNAME_R, HAS_GETPROTOBYNUMBER_R, HAS_GETPROTOENT_R, HAS_GETPWNAM_R, HAS_GETPWUID_R, HAS_GETSERVBYNAME_R, HAS_GETSERVBYPORT_R, HAS_GETSERVENT_R, HAS_GETSPNAM_R, HAS_RANDOM_R, HAS_READDIR_R, HAS_SETHOSTENT_R, HAS_SETNETENT_R, HAS_SETPROTOENT_R, HAS_SETSERVENT_R, HAS_SRANDOM_R, HAS_SRAND48_R, HAS_STRERROR_R, HAS_TMPNAM_R, HAS_TTYNAME_R, 

#ifdef HAS_STRNLEN
  use strnlen()
#else
  use an alternative implementation
#endif
, #ifdef HAS_STRNLEN use strnlen() #else use an alternative implementation #endif, #include, #include, #include, #define)

Пример использования:

#ifdef HAS_STRNLEN
  use strnlen()
#else
  use an alternative implementation
#endif

Список #include необходимых символов

Этот список содержит символы, которые указывают, присутствуют ли на платформе определённые #include файлы. Если ваш код использует функциональность, для которой требуется один из этих файлов, вам необходимо #include его, если символ в этом списке равен #defined. Для более подробной информации см. соответствующую запись в config.h.

I_ARPA_INET, I_BFD, I_CRYPT, I_DBM, I_DLFCN, I_EXECINFO, I_FP, I_FP_CLASS, I_GDBM, I_GDBMNDBM, I_GDBM_NDBM, I_GRP, I_IEEEFP, I_INTTYPES, I_LIBUTIL, I_MNTENT, I_NDBM, I_NETDB, I_NET_ERRNO, I_NETINET_IN, I_NETINET_TCP, I_PROT, I_PWD, I_RPCSVC_DBM, I_SGTTY, I_SHADOW, I_STDBOOL, I_STDINT, I_SUNMATH, I_SYS_ACCESS, I_SYS_IOCTL, I_SYSLOG, I_SYSMODE, I_SYS_MOUNT, I_SYS_PARAM, I_SYS_POLL, I_SYS_SECURITY, I_SYS_SELECT, I_SYS_STAT, I_SYS_STATVFS, I_SYS_SYSCALL, I_SYS_TIME, I_SYS_TIME_KERNEL, I_SYS_TIMES, I_SYS_TYPES, I_SYSUIO, I_SYS_UN, I_SYSUTSNAME, I_SYS_VFS, I_SYS_WAIT, I_TERMIO, I_TERMIOS, I_UNISTD, I_USTAT, I_VFORK, I_WCHAR, I_WCTYPE

Пример использования:

#ifdef I_WCHAR
  #include <wchar.h>
#endif

Глобальные переменные

Эти переменные являются глобальными для всего процесса. Они доступны для всех интерпретаторов и всех потоков в процессе. Любые переменные, не описанные здесь, могут быть изменены или удалены без предварительного уведомления, поэтому не используйте их! Если вы действительно считаете, что вам нужна неописанная переменная, отправьте письмо по адресу perl5-porters@perl.org. Возможно, кто-то там укажет способ достижения вашей цели без использования внутренней переменной. Но если нет, вы должны получить разрешение на документирование и использование переменной.

PL_check

Массив, индексированный по коду операции, функций, которые будут вызываться на стадии «check» построения дерева операций во время компиляции кода Perl. Для большинства (но не всех) типов операций, после того, как операция была первоначально построена и заполнена дочерними операциями, она будет отфильтрована через функцию проверки, указанную соответствующим элементом этого массива. Новый оператор передается в качестве единственного аргумента функции проверки, а функция проверки возвращает завершенный оператор. Функция проверки может (как следует из названия) проверить операцию на валидность и сообщить об ошибках. Она также может инициализировать или изменить части операций, или выполнить более радикальную операцию, такую как добавление или удаление дочерних операций, или даже удалить операцию и вернуть другую операцию вместо неё.

Этот массив указателей на функции является удобным местом для подключения к процессу компиляции. Модуль XS может поместить свою собственную пользовательскую функцию проверки вместо любой из стандартных, чтобы повлиять на компиляцию определённого типа операции. Однако пользовательская функция проверки никогда не должна полностью заменять стандартную функцию проверки (или даже пользовательскую функцию проверки из другого модуля). Модуль, изменяющий проверки, должен вместо этого обернуть существующую функцию проверки. Пользовательская функция проверки должна избирательно применять своё пользовательское поведение. В обычном случае, когда она решает ничего не делать со оператором, она должна вызвать предыдущую функцию проверки. Таким образом, функции проверки связаны в цепочке, с базовой проверкой ядра в конце.

Для обеспечения потокобезопасности модули не должны записывать непосредственно в этот массив. Вместо этого используйте функцию "wrap_op_checker".

PL_infix_plugin

ПРИМЕЧАНИЕ: PL_infix_plugin является экспериментальной и может быть изменена или удалена без предварительного уведомления.

ПРИМЕЧАНИЕ: Этот API существует исключительно для работы модуля XS::Parse::Infix с CPAN. Не ожидается, что дополнительные модули будут использовать его; вместо этого они должны использовать XS::Parse::Infix для обработки разбора новых инфиксных операторов.

Указатель на функцию, используемую для обработки расширенных инфиксных операторов. Функция должна быть объявлена как

int infix_plugin_function(pTHX_
        char *opname, STRLEN oplen,
        struct Perl_custom_infix **infix_ptr)

Функция вызывается из токенизатора всякий раз, когда встречается возможный инфиксный оператор. opname указывает на имя оператора в буфере ввода парсера, а oplen задаёт максимальное количество байтов, которое должно быть прочитано; оно не является нуль-терминированным. Ожидается, что функция проверит имя оператора и, возможно, другое состояние, такое как %^H, чтобы определить, хочет ли она обработать имя оператора.

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

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

Эта структура имеет следующее определение:

struct Perl_custom_infix {
    enum Perl_custom_infix_precedence prec;
    void (*parse)(pTHX_ SV **opdata,
	struct Perl_custom_infix *);
    OP *(*build_op)(pTHX_ SV **opdata, OP *lhs, OP *rhs,
	struct Perl_custom_infix *);
};

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

Если необязательная функция parse предоставлена, она вызывается парсером сразу, чтобы позволить определению оператора обработать любой дополнительный синтаксис из исходного кода. Это не должно использоваться для обычного разбора операндов, но может быть полезно при реализации таких вещей, как параметрические операторы или мета-операторы, которые потребляют больше синтаксиса сами. Эта функция может использовать переменную, на которую указывает opdata, для предоставления SV, содержащего дополнительные данные, которые будут переданы в функцию build_op позже.

Структура информации предоставляет уровень приоритета оператора в поле prec. Это используется для указания парсеру, сколько окружающего синтаксиса до и после следует рассматривать как операнды оператора.

Затем токенизатор и парсер будут продолжать работать в обычном режиме, пока не будет обработано достаточно дополнительного ввода для формирования левого и правого операндов оператора в соответствии с уровнем приоритета. В этот момент вызывается функция build_op, которой передаются левый и правый операнды в виде фрагментов дерева операций. Ожидается, что она объединит их в результирующий фрагмент дерева операций и вернёт его.

После возвращения функции build_op, если переменная, на которую указывает opdata, была установлена на значение, отличное от NULL, она будет уничтожена путём вызова SvREFCNT_dec().

Для обеспечения потокобезопасности модули не должны устанавливать эту переменную напрямую. Вместо этого используйте функцию "wrap_infix_plugin".

Однако, при всём при этом, вышеупомянутое вводное замечание всё ещё актуально. Эта переменная предоставляется в ядре Perl только для пользы модуля XS::Parse::Infix. Этот модуль действует как центральный реестр для инфиксных операторов, автоматически обрабатывая такие вещи, как поддержка депарсинга и обнаружение/рефлексия, и эти возможности работают только потому, что он знает все зарегистрированные операторы. Другие модули не должны использовать эту переменную интерпретатора напрямую для их реализации, потому что в противном случае эти центральные функции больше не будут работать должным образом.

Кроме того, вероятно, что этот (экспериментальный) API будет заменён в будущей версии Perl более полным API, который полностью реализует центральный реестр и другие семантики, в настоящее время предоставляемые XS::Parse::Infix, после достаточного времени экспериментальных испытаний модуля. Этот текущий механизм существует только как временная мера для достижения этой цели.

PL_keyword_plugin

ПРИМЕЧАНИЕ: PL_keyword_plugin является экспериментальной и может быть изменена или удалена без предварительного уведомления.

Указатель на функцию, используемую для обработки расширенных ключевых слов. Функция должна быть объявлена как

int keyword_plugin_function(pTHX_
        char *keyword_ptr, STRLEN keyword_len,
        OP **op_ptr)

Функция вызывается токенизатором, когда встречается потенциальное ключевое слово. keyword_ptr указывает на слово в буфере ввода парсера, а keyword_len задаёт его длину; оно не является нуль-терминированным. Ожидается, что функция проверит слово и, возможно, другое состояние, такое как %^H, чтобы определить, хочет ли она обработать его как расширенное ключевое слово. Если нет, функция должна вернуть KEYWORD_PLUGIN_DECLINE, и обычный процесс парсера продолжится.

Если функция хочет обработать ключевое слово, она сначала должна обработать всё, что следует за ключевым словом и является частью синтаксиса, введённого этим ключевым словом. Подробности см. в разделе "Интерфейс лексического анализатора".

Когда обрабатывается ключевое слово, функция-плагин должна построить дерево структур OP, представляющих обработанный код. Корень дерева должен быть сохранён в *op_ptr. Затем функция возвращает константу, указывающую синтаксическую роль обработанного конструкта: KEYWORD_PLUGIN_STMT, если это полное предложение, или KEYWORD_PLUGIN_EXPR, если это выражение. Обратите внимание, что конструкт предложения не может быть использован внутри выражения (кроме do BLOCK и аналогичных), а выражение не является полным предложением (требуется хотя бы завершающая точка с запятой).

Когда ключевое слово обрабатывается, функция-плагин может также иметь (во время компиляции) побочные эффекты. Она может изменять %^H, определять функции и так далее. Как правило, если побочные эффекты являются основной целью обработчика, он не хочет генерировать какие-либо операции для включения в обычную компиляцию. В этом случае всё равно необходимо предоставить дерево операций, но достаточно сгенерировать одиночную нулевую операцию.

Вот как функция *PL_keyword_plugin должна вести себя в целом. Однако, как правило, не следует полностью заменять существующую функцию обработчика. Вместо этого сделайте копию PL_keyword_plugin перед присвоением собственной функции-указателя. Ваша функция-обработчик должна искать ключевые слова, которые её интересуют, и обрабатывать их. В тех случаях, когда её не интересует то или иное ключевое слово, она должна вызвать сохранённую функцию-плагин, передавая полученные аргументы. Таким образом PL_keyword_plugin фактически указывает на цепочку функций-обработчиков, все из которых имеют возможность обрабатывать ключевые слова, и только последняя функция в цепочке (встроенная в ядро Perl) обычно возвращает KEYWORD_PLUGIN_DECLINE.

Для обеспечения потокобезопасности модули не должны устанавливать эту переменную напрямую. Вместо этого используйте функцию "wrap_keyword_plugin".

PL_phase

Значение, которое указывает текущую фазу интерпретатора Perl. Возможные значения включают PERL_PHASE_CONSTRUCT, PERL_PHASE_START, PERL_PHASE_CHECK, PERL_PHASE_INIT, PERL_PHASE_RUN, PERL_PHASE_END, и PERL_PHASE_DESTRUCT.

Например, следующее определяет, находится ли интерпретатор в глобальной фазе завершения:

if (PL_phase == PERL_PHASE_DESTRUCT) {
    // we are in global destruction
}

PL_phase была введена в Perl 5.14; в более ранних версиях Perl можно использовать PL_dirty (булево) для определения, находится ли интерпретатор в глобальной фазе завершения. (Использование PL_dirty не рекомендуется начиная с 5.14.)

enum perl_phase  PL_phase

Обработка GV и стеки

GV — это структура, соответствующая Perl-типоглобу, т. е. *foo. Это структура, которая содержит указатель на скаляр, массив, хеш и т. д., соответствующие $foo, @foo, %foo.

GV обычно встречаются в качестве значений в стеках (хешах таблицы символов), где Perl хранит свои глобальные переменные.

Стек — это хеш, содержащий все переменные, определённые в пакете. См. "Стеки и глобы" в perlguts

amagic_call

Выполните перегруженную (активную магическую) операцию, заданную method. method — одно из значений, найденных в overload.h.

flags влияет на то, как выполняется операция, следующим образом:

AMGf_noleft

left в этой операции не используется.

AMGf_noright

right в этой операции не используется.

AMGf_unary

Операция выполняется только над одним операндом.

AMGf_assign

Операция изменяет один из операндов, например, $x += 1

SV *  amagic_call(SV *left, SV *right, int method, int dir)
amagic_deref_call

Выполнить перегрузку оператора разыменования method для ref, вернув результат разыменования. method должно быть одной из операций разыменования, заданных в overload.h.

Если перегрузка отключена для ref, вернуть ref само по себе.

SV *  amagic_deref_call(SV *ref, int method)
gv_add_by_type

Убедитесь, что в GV gv есть слот типа type. 

GV *  gv_add_by_type(GV *gv, svtype type)
Gv_AMupdate

Пересчитывает магическую перегрузку в пакете, заданном stash.

Возвращает:

1 при успехе и наличии перегрузки
0, если перегрузки нет
-1, если произошла ошибка, и не удалось выполнить croak (потому что destructing равно true).
int  Gv_AMupdate(HV *stash, bool destructing)
gv_autoload_pv
gv_autoload_pvn
gv_autoload_sv

Каждый из них ищет метод AUTOLOAD, возвращая NULL, если не найден, или указатель на его GV, устанавливая переменную пакета $AUTOLOAD в значение name (полное квалифицированное имя). Кроме того, если найден и CV GV является XSUB, PV CV устанавливается в name, а его стекинг — в стекинг GV.

Поиск выполняется в MRO порядке, как указано в "gv_fetchmeth", начиная с stash , если оно не NULL.

Форматы различаются только способом задания name.

В gv_autoload_pv, namepv — строка C языка, завершающаяся нулём.

В gv_autoload_pvn, name указывает на первый байт имени, а дополнительный параметр len указывает его длину в байтах. Таким образом, *name может содержать вложенные нули.

В gv_autoload_sv, *namesv — SV, а имя — PV, извлечённое из него с помощью "SvPV". Если SV помечен как закодированный в UTF-8, извлечённый PV также будет.

GV *  gv_autoload_pv (HV *stash, const char *namepv, U32 flags)
GV *  gv_autoload_pvn(HV *stash, const char *name, STRLEN len,
                      U32 flags)
GV *  gv_autoload_sv (HV *stash, SV *namesv, U32 flags)
gv_autoload4

Эквивалентно "gv_autoload_pvn".

GV *  gv_autoload4(HV *stash, const char *name, STRLEN len,
                   I32 method)
GvAV

Возвращает AV из GV.

AV*  GvAV(GV* gv)
gv_AVadd
gv_HVadd
gv_IOadd
gv_SVadd

Убедитесь, что в GV gv есть слот заданного типа (AV, HV, IO, SV).

GV *  gv_AVadd(GV *gv)
gv_const_sv

Если gv — типглоб, чья подпрограмма входа — константная подпрограмма, пригодная для встраивания, или gv — ссылка-заполнитель, которая будет преобразована в такой типглоб, то возвращает значение, возвращаемое подпрограммой. В противном случае возвращает NULL.

SV *  gv_const_sv(GV *gv)
GvCV

Возвращает CV из GV.

CV*  GvCV(GV* gv)
gv_efullname3
gv_efullname4
gv_fullname3
gv_fullname4

Разместить полное имя пакета gv в sv. Формы gv_e* вместо этого возвращают эффективное имя пакета (см. "HvENAME").

Если prefix не NULL, он рассматривается как строка C, завершающаяся нулём, и хранимое имя будет ей предваряться.

Другое различие между функциями заключается в том, что формы *4 имеют дополнительный параметр keepmain. Если true, сохраняется начальный main:: в имени; если false, он удаляется. В формах *3 он всегда сохраняется.

void  gv_efullname3(SV *sv, const GV *gv, const char *prefix)
void  gv_efullname4(SV *sv, const GV *gv, const char *prefix,
                    bool keepmain)
void  gv_fullname3 (SV *sv, const GV *gv, const char *prefix)
void  gv_fullname4 (SV *sv, const GV *gv, const char *prefix,
                    bool keepmain)
gv_fetchfile
gv_fetchfile_flags

Возвращают дебаггер-глоб для файла (скомпилированный Perl), имя которого задаётся параметром name.

В настоящее время есть ровно два различия между этими функциями.

Параметр name функции gv_fetchfile — строка C, означающая, что она NUL-завершённая; в то время как параметр name функции gv_fetchfile_flags — строка Perl, длина которой (в байтах) передаётся через параметр namelen. Это означает, что имя может содержать вложенные NUL символы. namelen не существует в обычном gv_fetchfile.

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

GV *  gv_fetchfile      (const char *name)
GV *  gv_fetchfile_flags(const char * const name,
                         const STRLEN len, const U32 flags)
gv_fetchmeth
gv_fetchmeth_pv
gv_fetchmeth_pvn
gv_fetchmeth_sv

Каждый из них ищет типглоб с именем name, содержащий определённую подпрограмму, возвращая GV этого типглоба, если он найден, или NULL, если нет.

stash всегда ищется (сначала), если не NULL.

Если stash равно NULL или был просмотрен, но ничего не было найдено в нём, и бит GV_SUPER установлен в flags, затем просматриваются стекинг-слоты, доступные через @ISA. Поиск проводится в соответствии с MRO порядком.

Наконец, если до сих пор не было найдено совпадений, и флаг GV_NOUNIVERSAL в flags не установлен, проверяется UNIVERSAL::.

Аргумент level должен быть либо 0, либо -1. Если -1, функция вернётся без каких-либо побочных эффектов или кэширования. Если 0, функция убеждается, что в stash есть типглоб с именем name, создавая его при необходимости. Слот подпрограммы в типглобе будет установлен на любую подпрограмму, найденную в поисках stash и SUPER::, таким образом, кэшируя любой результат SUPER::. Обратите внимание, что подпрограммы, найденные в UNIVERSAL::, не кэшируются.

Возвращаемый GV может быть элементом кэша метода, который не виден коду Perl. Поэтому при вызове call_sv вы не должны использовать GV напрямую; вместо этого вы должны использовать CV метода, который можно получить из GV с помощью макроса GvCV.

Единственное другое значимое значение для flags — SVf_UTF8, указывающее на то, что name должен интерпретироваться как закодированный в UTF-8.

Обычный gv_fetchmeth не имеет параметра flags, поэтому всегда ищет в stash, затем в UNIVERSAL::, и name никогда не является UTF-8. В противном случае он точно такой же, как gv_fetchmeth_pvn.

Другие формы имеют параметр flags, и различаются только способом задания имени типглоба.

В gv_fetchmeth_pv, name — строка C языка, завершающаяся нулём.

В gv_fetchmeth_pvn, name указывает на первый байт имени, а дополнительный параметр len указывает его длину в байтах. Таким образом, имя может содержать вложенные нули.

В gv_fetchmeth_sv, *name — SV, а имя — PV, извлечённое из него с помощью "SvPV". Если SV помечен как закодированный в UTF-8, извлечённый PV также будет.

GV *  gv_fetchmeth    (HV *stash, const char *name, STRLEN len,
                       I32 level)
GV *  gv_fetchmeth_pv (HV *stash, const char *name, I32 level,
                       U32 flags)
GV *  gv_fetchmeth_pvn(HV *stash, const char *name, STRLEN len,
                       I32 level, U32 flags)
GV *  gv_fetchmeth_sv (HV *stash, SV *namesv, I32 level,
                       U32 flags)
gv_fetchmeth_autoload

Это старая форма "gv_fetchmeth_pvn_autoload", у которой нет параметра флагов.

GV *  gv_fetchmeth_autoload(HV *stash, const char *name,
                            STRLEN len, I32 level)
gv_fetchmethod

См. "gv_fetchmethod_autoload".

GV *  gv_fetchmethod(HV *stash, const char *name)
gv_fetchmethod_autoload

Возвращает типглоб, содержащий подпрограмму для вызова метода на stash. На самом деле, при наличии автозагрузки это может быть типглоб для "AUTOLOAD". В этом случае соответствующая переменная $AUTOLOAD уже настроена.

Третий параметр gv_fetchmethod_autoload определяет, выполняется ли поиск AUTOLOAD, если указанный метод отсутствует: ненулевое значение — да, ищем AUTOLOAD; нулевое — нет, не ищем AUTOLOAD. Вызов gv_fetchmethod эквивалентен вызову gv_fetchmethod_autoload с ненулевым параметром autoload.

Эти функции предоставляют "SUPER" как префикс имени метода. Обратите внимание, что если вы хотите сохранить возвращённый типглоб надолго, вам нужно проверить, является ли он "AUTOLOAD", так как в более позднее время вызов может загрузить другую подпрограмму из-за того, что значение $AUTOLOAD изменилось. Используйте созданный как побочный эффект типглоб, чтобы сделать это.

Эти функции имеют те же побочные эффекты, что и gv_fetchmeth с level==0. Предупреждение о передаче GV, возвращаемого gv_fetchmeth в call_sv, также относится к этим функциям.

GV *  gv_fetchmethod_autoload(HV *stash, const char *name,
                              I32 autoload)
gv_fetchmeth_pv_autoload

Точно так же, как "gv_fetchmeth_pvn_autoload", но принимает строку, завершённую нулём, вместо пары строка/длина.

GV *  gv_fetchmeth_pv_autoload(HV *stash, const char *name,
                               I32 level, U32 flags)
gv_fetchmeth_pvn_autoload

То же, что и gv_fetchmeth_pvn(), но также ищет подпрограммы с автозагрузкой. Возвращает типглоб подпрограммы.

Для подпрограммы с автозагрузкой без GV, создаст GV, даже если level < 0. Для подпрограммы с автозагрузкой без подпрограммы-заглушки GvCV() результата может быть равно нулю.

В настоящее время единственное значимое значение для flags — SVf_UTF8.

GV *  gv_fetchmeth_pvn_autoload(HV *stash, const char *name,
                                STRLEN len, I32 level, U32 flags)
END_OF_DOCUMENT_MARKER
gv_fetchmeth_sv_autoload

Точно так же, как "gv_fetchmeth_pvn_autoload", но принимает строку имени в виде SV, а не пары "строка/длина".

GV *  gv_fetchmeth_sv_autoload(HV *stash, SV *namesv, I32 level,
                               U32 flags)
gv_fetchpv
gv_fetchpvn
gv_fetchpvn_flags
gv_fetchpvs
gv_fetchsv
gv_fetchsv_nomg

Все эти функции возвращают GV типа sv_type, имя которого задано входными параметрами, или NULL, если GV с таким именем и типом не найдено. См. "Хранилища и глобальные переменные" в perlguts.

Единственные различия заключаются в том, как задаётся входное имя, и используется ли «магия получения» для получения этого имени.

Не обманывайтесь тем фактом, что только одна форма содержит flags в своём имени. Все они на самом деле имеют параметр flags, и все биты флагов имеют одинаковое значение для всех

Если установлен любой из флагов GV_ADD, GV_ADDMG, GV_ADDWARN, GV_ADDMULTI или GV_NOINIT, GV создаётся, если для входного имени и типа ещё не существует. Однако, GV_ADDMG выполнит создание только для магических GV. Для всех этих флагов, кроме GV_NOINIT, вызывается "gv_init_pvn" после добавления. GV_ADDWARN используется, когда вызывающая сторона ожидает, что добавление не потребуется, потому что символ уже должен существовать; но если нет, добавьте его, выдав предупреждение о том, что его неожиданно не было. Флаг GV_ADDMULTI означает, что GV якобы уже видела ранее (т.е., подавление предупреждений "Использовался один раз").

Флаг GV_NOADD_NOINIT вызывает то, что "gv_init_pvn" не будет вызываться, если GV существовала, но не является PVGV.

Если бит SVf_UTF8 установлен, имя обрабатывается как закодированное в UTF-8; в противном случае имя не будет рассматриваться как UTF-8 в формах с именем pv, а UTF-8-ность базовых SV будет использоваться в формах sv.

Если установлен флаг GV_NOTQUAL, вызывающая сторона гарантирует, что входное имя — это просто имя символа, а не квалифицированное с пакетом, в противном случае имя проверяется на квалификацию.

В gv_fetchpv, nambeg — это строка C, завершающаяся нулём без промежуточных нулей.

В gv_fetchpvs, name — это строка C в виде литерала, поэтому заключена в двойные кавычки.

gv_fetchpvn и gv_fetchpvn_flags идентичны. В них <nambeg> — это строка Perl, длина в байтах которой задаётся full_len, и она может содержать вставленные нули.

В gv_fetchsv и gv_fetchsv_nomg, имя извлекается из PV входного name SV. Единственное различие между этими двумя формами заключается в том, что «магия получения» обычно выполняется на name в gv_fetchsv, и всегда пропускается в gv_fetchsv_nomg. Включение GV_NO_SVGMAGIC в параметр flags функции gv_fetchsv заставляет её вести себя идентично функции gv_fetchsv_nomg. 

GV *  gv_fetchpv       (const char *nambeg, I32 flags,
                        const svtype sv_type)
GV *  gv_fetchpvn      (const char * nambeg, STRLEN full_len,
                        I32 flags, const svtype sv_type)
GV *  gv_fetchpvn_flags(const char *name, STRLEN len, I32 flags,
                        const svtype sv_type)
GV *  gv_fetchpvs      ("name", I32 flags, const svtype sv_type)
GV *  gv_fetchsv       (SV *name, I32 flags, const svtype sv_type)
GV *  gv_fetchsv_nomg  (SV *name, I32 flags, const svtype sv_type)
GvHV

Возвращает HV из GV.

HV*  GvHV(GV* gv)
gv_init

Старая форма gv_init_pvn(). Она не работает со строками UTF-8, так как не имеет параметра флагов. Если параметр multi установлен, флаг GV_ADDMULTI будет передан в gv_init_pvn(). 

void  gv_init(GV *gv, HV *stash, const char *name, STRLEN len,
              int multi)
gv_init_pv

То же, что и gv_init_pvn(), но принимает строку с завершающим нулём для имени вместо отдельных параметров char * и длина.

void  gv_init_pv(GV *gv, HV *stash, const char *name, U32 flags)
gv_init_pvn

Преобразует скаляр в типглоб. Это типглоб, не подлежащий приведению типов; присваивание ссылки ему приведет к присваиванию одному из его слотов, а не перезаписи, как происходит с типглобами, созданными с помощью SvSetSV. Преобразование любого скаляра, который является SvOK(), может привести к непредсказуемым результатам и предназначено для внутреннего использования Perl.

gv — это скаляр, который нужно преобразовать.

stash — хранилище/пакет-родитель, если таковой имеется.

name и len задают имя. Имя должно быть неквалифицированным, то есть не должно включать имя пакета. Если gv — элемент хранилища, вызывающая сторона отвечает за то, чтобы имя, переданное этой функции, совпадало с именем элемента. Если они не совпадают, внутренняя учётная запись Perl выйдет из строя.

flags может быть установлено в SVf_UTF8, если name — строка UTF-8, или значением возвращаемым SvUTF8(sv). Он также может принять флаг GV_ADDMULTI, который означает, что GV якобы уже была видела ранее (т.е., подавление предупреждений "Использовался один раз").

void  gv_init_pvn(GV *gv, HV *stash, const char *name, STRLEN len,
                  U32 flags)
gv_init_sv

То же, что и gv_init_pvn(), но принимает SV * для имени вместо отдельных параметров char * и длина. flags в настоящее время не используется.

void  gv_init_sv(GV *gv, HV *stash, SV *namesv, U32 flags)
gv_name_set

Установить имя для GV gv на name, которое имеет длину len байт. Таким образом, оно может содержать вставленные нули.

Если flags содержит SVf_UTF8, имя обрабатывается как закодированное в UTF-8; в противном случае — нет.

void  gv_name_set(GV *gv, const char *name, U32 len, U32 flags)
gv_stashpv

Возвращает указатель на хранилище для указанного пакета. Использует strlen для определения длины name, затем вызывает gv_stashpvn(). 

HV *  gv_stashpv(const char *name, I32 flags)
gv_stashpvn

Возвращает указатель на хранилище для указанного пакета. Параметр namelen указывает длину name, в байтах. flags передаётся в gv_fetchpvn_flags(), поэтому если установлено в GV_ADD, пакет будет создан, если он ещё не существует. Если пакет не существует, и flags равно 0 (или любое другое значение, не создающее пакеты), то возвращается NULL.

Флаги могут быть следующими:

GV_ADD           Create and initialize the package if doesn't
                 already exist
GV_NOADD_NOINIT  Don't create the package,
GV_ADDMG         GV_ADD iff the GV is magical
GV_NOINIT        GV_ADD, but don't initialize
GV_NOEXPAND      Don't expand SvOK() entries to PVGV
SVf_UTF8         The name is in UTF-8

Наиболее важными из них, вероятно, являются GV_ADD и SVf_UTF8.

Обратите внимание, что использование gv_stashsv вместо gv_stashpvn, где это возможно, настоятельно рекомендуется по соображениям производительности.

HV *  gv_stashpvn(const char *name, U32 namelen, I32 flags)
gv_stashpvs

Подобно gv_stashpvn, но принимает строку-литерал вместо пары "строка/длина".

HV*  gv_stashpvs("name", I32 create)
gv_stashsv

Возвращает указатель на хранилище для указанного пакета. См. "gv_stashpvn".

Обратите внимание, что этот интерфейс предпочтительнее gv_stashpvn по соображениям производительности.

HV *  gv_stashsv(SV *sv, I32 flags)
GvSV

Возвращает SV из GV.

До Perl v5.9.3, это добавляло скаляр, если он не существовал. В настоящее время для этого используйте "GvSVn", или скомпилируйте Perl с -DPERL_CREATE_GVSV. См. perl5100delta.

SV*  GvSV(GV* gv)
GvSVn

Аналогично "GvSV", но создаёт пустой скаляр, если он не существует.

SV*  GvSVn(GV* gv)
newGVgen
newGVgen_flags

Создаёт новый, гарантированно уникальный GV в пакете, заданном строкой C языка с завершающим нулём pack, и возвращает указатель на него.

Для newGVgen или если flags в newGVgen_flags равно 0, pack должен рассматриваться как закодированный в Latin-1. Единственное другое допустимое значение flags — это SVf_UTF8, что указывает на то, что pack должно рассматриваться как закодированное в UTF-8.

GV *  newGVgen      (const char *pack)
GV *  newGVgen_flags(const char *pack, U32 flags)
PL_curstash

Хранилище для пакета, код которого будет компилироваться.

В многопоточных Perl-ях каждый поток имеет независимую копию этой переменной; каждый инициализируется при создании текущим значением копии создающего потока.

HV*  PL_curstash
PL_defgv

GV, представляющая *_. Полезно для доступа к $_.

В многопоточных Perl-ях каждый поток имеет независимую копию этой переменной; каждый инициализируется при создании текущим значением копии создающего потока.

GV *  PL_defgv
PL_defoutgv

См. "setdefout".

PL_defstash

Описание в perlguts.

save_gp

Сохраняет текущий GP gv в стеке сохранения для восстановления при выходе из области видимости.

Если empty истинно, заменяет GP новым GP.

Если empty ложно, помечает gv флагом GVf_INTRO, чтобы следующая присвоенная ссылка была локальной, что и используется в local *foo = $someref; .

void  save_gp(GV *gv, I32 empty)
setdefout

Устанавливает PL_defoutgv, стандартный дескриптор файла для вывода, на переданный типглоб. Поскольку PL_defoutgv «владеет» ссылкой на свой типглоб, счётчик ссылок на переданный типглоб увеличивается на единицу, а счётчик ссылок на типглоб, на который указывает PL_defoutgv, уменьшается на единицу.

void  setdefout(GV *gv)

Управление хуками

Эти функции предоставляют удобный и потокобезопасный способ управления переменными хуков.

rcpv_copy

Увеличивает счётчик ссылок на строку с совместным доступом в памяти, а когда счётчик ссылок становится равным 0, освобождает её с помощью PerlMemShared_free().

Вызывающая сторона должна убедиться, что pv является результатом вызова rcpv_new().

Возвращает тот же указатель, что был передан.

new = rcpv_copy(pv);
char *  rcpv_copy(char * const pv)
rcpv_free

Уменьшает счётчик ссылок на строку с совместным доступом в памяти, а когда счётчик ссылок становится равным 0, освобождает её с помощью perlmemshared_free().

Вызывающая сторона должна убедиться, что pv является результатом вызова rcpv_new().

Всегда возвращает NULL, чтобы его можно было использовать так:

thing = rcpv_free(thing);
char *  rcpv_free(char * const pv)
rcpv_new

Создаёт новую ссылку на строку в общей памяти с заданным размером, инициализацией и счётчиком ссылок, равным 1. Фактическое выделенное пространство будет на 1 байт больше запрошенного, и rcpv_new() гарантирует, что дополнительный байт будет нулём независимо от настроек флагов.

Если установлен флаг RCPVf_NO_COPY, то аргумент pv будет проигнорирован, в противном случае содержимое указателя pv будет скопировано в новый буфер. Если pv равен NULL, функция ничего не сделает и вернёт NULL.

Если установлен флаг RCPVf_USE_STRLEN, то аргумент len игнорируется, и пересчитывается с использованием strlen(pv). Одновременное использование RCPVf_USE_STRLEN и RCPVf_NO_COPY является ошибкой.

В режиме отладки rcpv_new() выполнит assert(), если запрошено создание строки длиной 0, если не установлен флаг RCPVf_ALLOW_EMPTY.

Возвращаемое значение функции подходит для передачи в rcpv_copy() и rcpv_free(). Для доступа к RCPV * из возвращаемого значения используйте макрос RCPVx(). Член 'len' структуры RCPV хранит выделенную длину (включая дополнительный байт), но макрос RCPV_LEN() возвращает запрошенную длину (без дополнительного байта).

Обратите внимание, что rcpv_new() НЕ использует хеш-таблицу или что-либо подобное для избегания дублирования входных данных с одинаковым текстовым содержимым. Каждый вызов с параметром pv, отличным от NULL, породит отдельный указатель со своим счётчиком ссылок, независимо от содержимого входных данных.

char *  rcpv_new(const char * const pv, STRLEN len, U32 flags)
wrap_op_checker

Добавляет C-функцию в цепочку функций проверки для указанного типа операции. Это предпочтительный способ управления массивом "PL_check". opcode определяет тип операции, на которую будет повлиять функция. new_checker — указатель на C-функцию, которая должна быть добавлена в цепочку проверки для данного кода операции, а old_checker_p указывает место хранения указателя на следующую функцию в цепочке. Значение new_checker записывается в массив "PL_check", а ранее сохранённое значение записывается в *old_checker_p.

Массив "PL_check" глобален для всего процесса, и модуль, желающий подключиться к проверке операций, может быть вызван более одного раза в процессе, обычно в разных потоках. Для обработки такой ситуации функция идемпотентна. Место *old_checker_p должно изначально (один раз на процесс) содержать нулевой указатель. C-переменная со статическим сроком существования (объявленная на уровне файла, обычно также помеченная как static для обеспечения внутренней связи) будет неявно инициализирована должным образом, если у неё нет явного инициализатора. Данная функция будет фактически изменять цепочку проверки только в случае, если *old_checker_p окажется нулевым указателем. Эта функция также потокобезопасна в малом масштабе. Она использует соответствующую блокировку для предотвращения гонок при доступе к "PL_check".

Когда эта функция вызывается, функция, на которую ссылается new_checker, должна быть готова к вызову, за исключением того, что *old_checker_p не заполнено. В ситуации с несколькими потоками new_checker может быть вызвана немедленно, даже до возврата этой функции. *old_checker_p всегда будет должным образом установлено перед вызовом new_checker. Если new_checker решает не выполнять никаких специальных действий с данной операцией (что является обычным случаем для большинства случаев подключения к проверке операций), то она должна передать проверку функции, на которую ссылается *old_checker_p.

В целом, код XS для подключения проверки операции обычно выглядит так:

static Perl_check_t nxck_frob;
static OP *myck_frob(pTHX_ OP *op) {
    ...
    op = nxck_frob(aTHX_ op);
    ...
    return op;
}
BOOT:
    wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);

Если вы хотите повлиять на компиляцию вызовов конкретной подпрограммы, используйте "cv_set_call_checker_flags", а не подключение проверки всех entersub операций.

void  wrap_op_checker(Optype opcode, Perl_check_t new_checker,
                      Perl_check_t *old_checker_p)

Обработка HV

Структура HV представляет собой Perl-хеш. Она в основном состоит из массива указателей, каждый из которых указывает на список связанных структур HE. Массив индексируется по хеш-функции ключа, поэтому каждый список связанных элементов представляет все записи хеша с одинаковым значением хеша. Каждая HE содержит указатель на фактическое значение, а также указатель на структуру HEK, которая содержит ключ и значение хеша.

get_hv

Возвращает HV указанного Perl-хеша. flags передаются в gv_fetchpv. Если GV_ADD установлено, а Perl-переменная не существует, то она будет создана. Если flags равно нулю (игнорируя SVf_UTF8) и переменная не существует, то возвращается NULL.

ПРИМЕЧАНИЕ: форма perl_get_hv() устарела.

HV *  get_hv(const char *name, I32 flags)
HE

Описано в perlguts.

HEf_SVKEY

Этот флаг, используемый в поле длины записей хеша и магических структур, указывает, что структура содержит указатель SV*, где ожидается указатель char*. (Для справки — не для использования).

HeHASH

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

U32  HeHASH(HE* he)
HeKEY

Возвращает фактический указатель, хранящийся в поле ключа записи хеша. Указатель может быть либо char*, либо SV*, в зависимости от значения HeKLEN(). Может быть присвоено значение. Макросы HePV() или HeSVKEY() обычно предпочтительнее для определения значения ключа.

void*  HeKEY(HE* he)
HeKLEN

Если это отрицательное значение и соответствует HEf_SVKEY, это указывает, что запись содержит ключ SV*. В противном случае хранит фактическую длину ключа. Может быть присвоено значение. Макрос HePV() обычно предпочтительнее для получения длин ключей.

STRLEN  HeKLEN(HE* he)
HePV

Возвращает поле ключа записи хеша как значение char*, выполняя необходимые операции разыменования, если ключ потенциально SV*. Длина строки помещается в len (это макрос, поэтому не используйте &len). Если длина ключа не важна, можно использовать глобальную переменную PL_na, хотя это несколько менее эффективно, чем использование локальной переменной. Однако помните, что ключи хеша в Perl могут содержать вложенные нули, поэтому использование strlen() или аналогичных методов не является хорошим способом определения длины ключей хеша. Это очень похоже на макрос SvPV(), описанный в другом месте этого документа. См. также "HeUTF8".

Если вы используете HePV для получения значений, которые нужно передать в newSVpvn() для создания нового SV, рассмотрите использование newSVhek(HeKEY_hek(he)), так как это более эффективно.

char*  HePV(HE* he, STRLEN len)
HeSVKEY

Возвращает ключ как SV*, или NULL, если запись хеша не содержит ключ SV*. 

SV*  HeSVKEY(HE* he)
HeSVKEY_force

Возвращает ключ как SV*. Создаст и вернёт временную смертную SV*, если запись хеша содержит только ключ char*. 

SV*  HeSVKEY_force(HE* he)
HeSVKEY_set

Устанавливает ключ на заданное SV*, заботясь об установке соответствующих флагов для обозначения наличия ключа SV*, и возвращает то же самое SV*.

SV*  HeSVKEY_set(HE* he, SV* sv)
HeUTF8

Возвращает, закодировано ли значение char *, возвращённое HePV, в UTF-8, выполняя необходимые операции разыменования, если ключ потенциально SV*. Возвращаемое значение будет 0 или ненулевым, не обязательно 1 (или даже значением с установленными битами), поэтому не присваивайте его напрямую переменной bool, так как bool может быть псевдонимом для char.

U32  HeUTF8(HE* he)
HeVAL

Возвращает поле значения (тип SV*) хранящееся в записи хеша. Может быть присвоено значение.

SV *foo= HeVAL(hv);
HeVAL(hv)= sv;
SV*  HeVAL(HE* he)
HV

Описано в perlguts.

hv_assert

Проверяет, находится ли хеш в внутренне согласованном состоянии.

ПРИМЕЧАНИЕ: hv_assert должен быть явным образом вызван как Perl_hv_assert с параметром aTHX_.

void  Perl_hv_assert(pTHX_ HV *hv)
hv_bucket_ratio

ПРИМЕЧАНИЕ: hv_bucket_ratio является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Если хеш привязан и перенаправляет вызовы через метод SCALAR, иначе, если хеш не содержит ключей, возвращает 0, иначе возвращает временный SV, содержащий строку, определяющую количество используемых ведер, за которой следует косая черта, за которой следует количество доступных ведер.

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

SV *  hv_bucket_ratio(HV *hv)
hv_clear

Освобождает все элементы хеша, оставляя его пустым. XS-эквивалент %hash = (). См. также "hv_undef".

См. "av_clear" для примечания о том, что хеш потенциально может быть недействительным по возвращении.

void  hv_clear(HV *hv)
hv_clear_placeholders

Очищает все заполнительные ключи из хеша. Если в ограниченном хеше у некоторых ключей установлен флаг readonly и ключ впоследствии удаляется, ключ фактически не удаляется, а помечается присвоением ему значения &PL_sv_placeholder. Это помечает его для игнорирования в будущих операциях, таких как итерация по хешу, но позволит хешу повторно присвоить значение ключу в будущем. Эта функция очищает все такие заполнительные ключи из хеша. См. Hash::Util::lock_keys() для примера использования.

void  hv_clear_placeholders(HV *hv)
hv_copy_hints_hv

Специализированная версия "newHVhv" для копирования %^H. ohv должен быть указателем на хеш (который может иметь магию %^H, но обычно не должен быть магическим), или NULL (интерпретируется как пустой хеш). Содержимое ohv копируется в новый хеш, которому добавляется специфичная для %^H магия. Возвращается указатель на новый хеш.

HV *  hv_copy_hints_hv(HV * const ohv)
hv_delete

Удаляет пару ключ/значение из хеша. SV значения удаляется из хеша, становится смертным и возвращается вызывающей стороне. Абсолютное значение klen — длина ключа. Если klen отрицательно, предполагается, что ключ закодирован в UTF-8 Unicode. Значение flags обычно равно нулю; если оно установлено в G_DISCARD, то будет возвращено NULL. NULL также будет возвращено, если ключ не найден.

SV *  hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
hv_delete_ent

Удаляет пару ключ/значение в хэше. Значение SV удаляется из хэша, становится смертным и возвращается вызывающему коду. Значение flags обычно равно нулю; если установлено значение G_DISCARD, то будет возвращено значение NULL. NULL также будет возвращено, если ключ не найден. hash может быть допустимым предварительно вычисленным значением хэша или 0, чтобы запросить его вычисление.

SV *  hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
HvENAME

Возвращает эффективное имя хранилища или NULL, если его нет. Эффективное имя представляет собой местоположение в таблице символов, где находится это хранилище. Оно обновляется автоматически при алиасировании или удалении пакетов. Хранилище, которое больше не находится в таблице символов, не имеет эффективного имени. Это имя предпочтительнее HvNAME для использования в линейных упорядоченных списках MRO и кэшах isa.

char*  HvENAME(HV* stash)
HvENAMELEN

Возвращает длину эффективного имени хранилища.

STRLEN  HvENAMELEN(HV *stash)
HvENAMEUTF8

Возвращает true, если эффективное имя закодировано в UTF-8.

unsigned char  HvENAMEUTF8(HV *stash)
hv_exists

Возвращает булево значение, указывающее, существует ли указанный ключ хэша. Абсолютное значение klen — длина ключа. Если klen отрицательно, предполагается, что ключ закодирован в UTF-8 Unicode.

bool  hv_exists(HV *hv, const char *key, I32 klen)
hv_exists_ent

Возвращает булево значение, указывающее, существует ли указанный ключ хэша. hash может быть допустимым предварительно вычисленным значением хэша или 0, чтобы запросить его вычисление.

bool  hv_exists_ent(HV *hv, SV *keysv, U32 hash)
hv_fetch

Возвращает SV, соответствующий указанному ключу в хэше. Абсолютное значение klen — длина ключа. Если klen отрицательно, предполагается, что ключ закодирован в UTF-8 Unicode. Если lval установлено, запрос будет частью сохранения. Это означает, что если в хэше нет значения, связанного с заданным ключом, то создаётся одно, и возвращается указатель на него. К которому можно присвоить значение SV*. Но всегда проверяйте, что возвращаемое значение не равно null, прежде чем разыменовывать его в SV*.

См. "Understanding the Magic of Tied Hashes and Arrays" в perlguts для получения дополнительной информации об использовании этой функции с привязанными хэшами.

SV **  hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
hv_fetch_ent

Возвращает запись хэша, соответствующую указанному ключу в хэше. hash должен быть допустимым предварительно вычисленным числом хэша для данного key, или 0, если вы хотите, чтобы функция его вычислила. Если lval установлено, запрос будет частью сохранения. Убедитесь, что возвращаемое значение не равно null, прежде чем обращаться к нему. Возвращаемое значение, когда hv — привязанный хэш, — указатель на статическое местоположение, поэтому обязательно скопируйте структуру, если вам нужно сохранить её где-либо.

См. "Understanding the Magic of Tied Hashes and Arrays" в perlguts для получения дополнительной информации об использовании этой функции с привязанными хэшами.

HE *  hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
hv_fetchs

Аналогично hv_fetch, но принимает строку-литерал вместо пары "строка/длина".

SV**  hv_fetchs(HV* tb, "key", I32 lval)
HvFILL

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

Начиная с perl 5.25 эта функция используется только для отладки, и количество используемых корзин хэша никак не кэшируется, поэтому эта функция может быть дорогостоящей для выполнения, так как ей нужно перебрать все корзины в хэше.

STRLEN  HvFILL(HV *const hv)
HvHasAUX

Возвращает true, если HV имеет расширение struct xpvhv_aux. Используйте это, чтобы проверить, можно ли вызвать HvAUX(). 

bool  HvHasAUX(HV *const hv)
hv_iterinit

Подготавливает начальную точку для обхода таблицы хэша. Возвращает количество ключей в хэше, включая заполнитель (т.е. то же самое, что и HvTOTALKEYS(hv)). Возвращаемое значение в настоящее время имеет смысл только для хэшей без магии привязки.

ПРИМЕЧАНИЕ: До версии 5.004_65 hv_iterinit возвращало количество используемых корзин хэша. Если вам всё ещё нужно это экзотическое значение, вы можете получить его через макрос HvFILL(hv). 

I32  hv_iterinit(HV *hv)
hv_iterkey

Возвращает ключ из текущей позиции итератора хэша. См. "hv_iterinit". 

char *  hv_iterkey(HE *entry, I32 *retlen)
hv_iterkeysv

Возвращает ключ как SV* из текущей позиции итератора хэша. Возвращаемое значение всегда является смертной копией ключа. Также см. "hv_iterinit". 

SV *  hv_iterkeysv(HE *entry)
hv_iternext

Возвращает записи из итератора хэша. См. "hv_iterinit".

Вы можете вызвать hv_delete или hv_delete_ent на записи хэша, на которую итератор в данный момент указывает, не теряя своего места или не делая свой итератор недействительным. Обратите внимание, что в этом случае текущая запись удаляется из хэша с помощью вашего итератора, удерживающего последнюю ссылку на неё. Ваш итератор помечен для освобождения записи при следующем вызове hv_iternext, поэтому не следует сразу удалять свой итератор, иначе запись утечёт — вызовите hv_iternext, чтобы инициировать освобождение ресурса.

HE *  hv_iternext(HV *hv)
hv_iternext_flags

ПРИМЕЧАНИЕ: hv_iternext_flags является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Возвращает записи из итератора хэша. См. "hv_iterinit" и "hv_iternext". Значение flags обычно равно нулю; если HV_ITERNEXT_WANTPLACEHOLDERS установлено, то возвращаются ключи-заполнители (для ограниченных хэшей) в дополнение к обычным ключам. По умолчанию заполнители автоматически пропускаются. В настоящее время заполнитель реализуется со значением &PL_sv_placeholder. Обратите внимание, что реализация заполнителей и ограниченных хэшей может измениться, и текущая реализация недостаточно абстрактна для того, чтобы любое изменение было аккуратным.

HE *  hv_iternext_flags(HV *hv, I32 flags)
hv_iternextsv

Выполняет hv_iternext, hv_iterkey и hv_iterval в одной операции.

SV *  hv_iternextsv(HV *hv, char **key, I32 *retlen)
hv_iterval

Возвращает значение из текущей позиции итератора хэша. См. "hv_iterkey". 

SV *  hv_iterval(HV *hv, HE *entry)
hv_ksplit

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

Это то же самое, что сделать следующее в коде Perl:

keys %hv = newmax;
void  hv_ksplit(HV *hv, IV newmax)
hv_magic

Добавляет магию к хэшу. См. "sv_magic". 

void  hv_magic(HV *hv, GV *gv, int how)
HvNAME

Возвращает имя пакета хранилища или NULL, если stash не является хранилищем. См. "SvSTASH", "CvSTASH". 

char*  HvNAME(HV* stash)
HvNAMELEN

Возвращает длину имени хранилища.

Не рекомендуемые формы HvNAME и HvNAMELEN; подавить упоминание о них

STRLEN  HvNAMELEN(HV *stash)
hv_name_set
hv_name_sets

Эти функции устанавливают имя хранилища hv на указанное имя.

Они отличаются только способом указания имени.

В hv_name_sets, имя — это строка C-литерал, заключённая в двойные кавычки.

В hv_name_set, name указывает на первый байт имени, а дополнительный параметр len задаёт его длину в байтах. Таким образом, имя может содержать встроенные символы NULL.

Если SVf_UTF8 установлено в flags, имя обрабатывается как UTF-8; в противном случае — нет.

Если HV_NAME_SETALL установлено в flags, устанавливаются и имя, и эффективное имя.

void  hv_name_set (HV *hv, const char *name, U32 len, U32 flags)
void  hv_name_sets(HV *hv, "name", U32 flags)
HvNAMEUTF8

Возвращает true, если имя закодировано в UTF-8.

unsigned char  HvNAMEUTF8(HV *stash)
hv_scalar

Оценивает хэш в контексте скаляра и возвращает результат.

При привязанном хэше выполняет обращение к методу SCALAR, иначе возвращает смертное SV, содержащее количество ключей в хэше.

Обратите внимание, что до 5.25 эта функция возвращала то, что сейчас возвращает функция hv_bucket_ratio().

SV *  hv_scalar(HV *hv)
hv_store
hv_stores

Эти функции хранят SV val со значением, указанным в ключе в хэше hv, возвращая NULL, если операция не удалась или значение не нужно было фактически хранить в хэше (например, в случае привязанных хэшей). В противном случае к нему можно обратиться, чтобы получить исходный SV*.

Они различаются только способом указания ключа хэша.

В hv_stores, ключ — это строковая константа языка C, заключённая в двойные кавычки. Она никогда не обрабатывается как UTF-8.

В hv_store, key либо равен NULL, либо указывает на первый байт строки, определяющей ключ, а её длина в байтах задаётся абсолютным значением дополнительного параметра, klen. Ключ NULL указывает, что ключ должен обрабатываться как undef, и klen игнорируется; в противном случае строка ключа может содержать вставленные нулевые байты. Если klen отрицательно, строка обрабатывается как закодированная в UTF-8; в противном случае — нет.

hv_store имеет ещё один дополнительный параметр, hash, предварительно вычисленный хэш строки ключа или ноль, если он не был предварительно вычислен. Этот параметр опущен из hv_stores, так как он вычисляется автоматически во время компиляции.

Если <hv> равен NULL, возвращается NULL, и никаких действий не выполняется.

Если val равен NULL, он обрабатывается как undef; в противном случае вызывающая сторона отвечает за надлежащее увеличение счётчика ссылок на val перед вызовом и уменьшение его, если функция вернула NULL. По сути, успешный hv_store принимает на себя одну ссылку на val. Это обычно то, что нужно; у только что созданного SV счётчик ссылок равен единице, поэтому если весь ваш код создаёт SV и сохраняет их в хэше, hv_store будет обладать единственной ссылкой на новый SV, и вашему коду не нужно будет предпринимать никаких дополнительных действий для упорядочения.

hv_store не реализован как вызов "hv_store_ent" и не создаёт временный SV для ключа, поэтому если данные ключа не представлены в виде SV, используйте hv_store вместо hv_store_ent.

См. "Понимание магии привязанных хэшей и массивов" в perlguts для получения дополнительной информации о том, как использовать эту функцию с привязанными хэшами.

SV **  hv_store (HV *hv, const char *key, I32 klen, SV *val,
                 U32 hash)
SV **  hv_stores(HV *hv, "key", SV *val)
hv_store_ent

Хранит val в хэше. Ключ хэша задаётся как key. Параметр hash — предварительно вычисленное значение хэша; если оно равно нулю, Perl вычислит его. Возвращаемое значение — новый созданный элемент хэша. Он будет NULL если операция не удалась или если значение не нужно было фактически хранить в хэше (например, в случае привязанных хэшей). В противном случае содержимое возвращаемого значения можно получить с помощью макросов He? описанных здесь. Обратите внимание, что вызывающая сторона отвечает за надлежащее увеличение счётчика ссылок на val перед вызовом и уменьшение его, если функция вернула NULL. По сути, успешный hv_store_ent принимает на себя одну ссылку на val. Это обычно то, что нужно; у только что созданного SV счётчик ссылок равен единице, поэтому если весь ваш код создаёт SV и сохраняет их в хэше, hv_store будет обладать единственной ссылкой на новый SV, и вашему коду не нужно будет предпринимать никаких дополнительных действий для упорядочения. Обратите внимание, что hv_store_ent только считывает key; в отличие от val, он не принимает на себя ответственность за него, поэтому поддержание правильного счётчика ссылок на key полностью возложено на вызывающую сторону. Причина, по которой он не принимает на себя ответственность, заключается в том, что key не используется после возвращения этой функции и поэтому может быть освобождён немедленно. hv_store не реализован как вызов hv_store_ent, и не создаёт временный SV для ключа, поэтому если данные ключа не представлены в виде SV, используйте hv_store вместо hv_store_ent.

См. "Понимание магии привязанных хэшей и массивов" в perlguts для получения дополнительной информации о том, как использовать эту функцию с привязанными хэшами.

HE *  hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
hv_undef

Удаляет хэш. Аналог undef(%hash) на C.

Помимо освобождения всех элементов хэша (как hv_clear()), это также освобождает любые вспомогательные данные и память, связанные с хэшем.

См. "av_clear" для примечания о том, что хэш может стать недопустимым при возврате.

void  hv_undef(HV *hv)
newHV

Создаёт новый HV. Счётчик ссылок устанавливается в 1.

HV *  newHV()
newHVhv

Содержимое ohv копируется в новый хэш. Возвращается указатель на новый хэш.

HV *  newHVhv(HV *hv)
Nullhv

DEPRECATED! Планируется удалить Nullhv из будущих релизов Perl. Не используйте его в новом коде; удалите его из существующего кода.

Указатель на пустой HV.

(устаревший — используйте (HV *)NULL вместо этого)

PERL_HASH

Описание в perlguts.

void  PERL_HASH(U32 hash, char *key, STRLEN klen)
PL_modglobal

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

В многопоточных Perl'ях каждый поток имеет независимую копию этой переменной; каждая из них инициализируется при создании текущим значением копии потока, выполняющего создание.

HV*  PL_modglobal

Вход/Выход

do_close

Закрыть поток ввода/вывода. Эта функция реализует Perl "close" в perlfunc.

gv — glob, связанный с потоком.

is_explict — true, если это явное закрытие потока; false, если это часть другой операции, такой как закрытие канала (что подразумевает закрытие обоих концов).

Возвращает true при успехе; в противном случае возвращает false и устанавливает errno для указания причины.

bool  do_close(GV *gv, bool is_explicit)
IoDIRP

Описание в perlguts.

DIR *  IoDIRP(IO *io)
IOf_FLUSH

Описание в perlguts.

IoFLAGS

Описание в perlguts.

U8  IoFLAGS(IO *io)
IOf_UNTAINT

Описание в perlguts.

IoIFP

Описание в perlguts.

PerlIO *  IoIFP(IO *io)
IoOFP

Описание в perlguts.

PerlIO *  IoOFP(IO *io)
IoTYPE

Описание в perlguts.

char  IoTYPE(IO *io)
my_chsize

Функция chsize(3) из C-библиотеки, если доступна, или её реализация в Perl.

I32  my_chsize(int fd, Off_t length)
my_dirfd

Функция dirfd(3) из C-библиотеки, если доступна, или её реализация в Perl, либо сообщение об ошибке, если её сложно эмулировать.

int  my_dirfd(DIR *dir)
my_pclose

Обёртка для C-функции pclose(3). Не используйте последнюю, так как Perl-версия знает аспекты взаимодействия с остальной частью интерпретатора Perl.

I32  my_pclose(PerlIO *ptr)
my_popen

Обёртка для C-функции popen(3). Не используйте последнюю, так как Perl-версия знает аспекты взаимодействия с остальной частью интерпретатора Perl.

PerlIO *  my_popen(const char *cmd, const char *mode)
newIO

Создать новый IO, установив счётчик ссылок в 1.

IO *  newIO()
PERL_FLUSHALL_FOR_CHILD

Определяет способ очистки всех буферов вывода. Это может быть проблемой производительности, поэтому мы позволяем пользователям её отключить. Кроме того, если мы используем stdio, существуют нерабочие реализации fflush(NULL) — Solaris — наиболее заметный пример.

void  PERL_FLUSHALL_FOR_CHILD
PerlIO_apply_layers
PerlIO_binmode
PerlIO_canset_cnt
PerlIO_clearerr
PerlIO_close
PerlIO_debug
PerlIO_eof
PerlIO_error
PerlIO_exportFILE
PerlIO_fast_gets
PerlIO_fdopen
PerlIO_fileno
PerlIO_fill
PerlIO_findFILE
PerlIO_flush
PerlIO_get_base
PerlIO_get_bufsiz
PerlIO_get_cnt
PerlIO_get_ptr
PerlIO_getc
PerlIO_getpos
PerlIO_has_base
PerlIO_has_cntptr
PerlIO_importFILE
PerlIO_open
PerlIO_printf
PerlIO_putc
PerlIO_puts
PerlIO_read
PerlIO_releaseFILE
PerlIO_reopen
PerlIO_rewind
PerlIO_seek
PerlIO_set_cnt
PerlIO_set_ptrcnt
PerlIO_setlinebuf
PerlIO_setpos
PerlIO_stderr
PerlIO_stdin
PerlIO_stdout
PerlIO_stdoutf
PerlIO_tell
PerlIO_ungetc
PerlIO_unread
PerlIO_vprintf
PerlIO_write

Описание в perlapio.

int        PerlIO_apply_layers(PerlIO *f, const char *mode,
                               const char *layers)
int        PerlIO_binmode     (PerlIO *f, int ptype, int imode,
                               const char *layers)
int        PerlIO_canset_cnt  (PerlIO *f)
void       PerlIO_clearerr    (PerlIO *f)
int        PerlIO_close       (PerlIO *f)
void       PerlIO_debug       (const char *fmt, ...)
int        PerlIO_eof         (PerlIO *f)
int        PerlIO_error       (PerlIO *f)
FILE *     PerlIO_exportFILE  (PerlIO *f, const char *mode)
int        PerlIO_fast_gets   (PerlIO *f)
PerlIO *   PerlIO_fdopen      (int fd, const char *mode)
int        PerlIO_fileno      (PerlIO *f)
int        PerlIO_fill        (PerlIO *f)
FILE *     PerlIO_findFILE    (PerlIO *f)
int        PerlIO_flush       (PerlIO *f)
STDCHAR *  PerlIO_get_base    (PerlIO *f)
SSize_t    PerlIO_get_bufsiz  (PerlIO *f)
SSize_t    PerlIO_get_cnt     (PerlIO *f)
STDCHAR *  PerlIO_get_ptr     (PerlIO *f)
int        PerlIO_getc        (PerlIO *d)
int        PerlIO_getpos      (PerlIO *f, SV *save)
int        PerlIO_has_base    (PerlIO *f)
int        PerlIO_has_cntptr  (PerlIO *f)
PerlIO *   PerlIO_importFILE  (FILE *stdio, const char *mode)
PerlIO *   PerlIO_open        (const char *path, const char *mode)
int        PerlIO_printf      (PerlIO *f, const char *fmt, ...)
int        PerlIO_putc        (PerlIO *f, int ch)
int        PerlIO_puts        (PerlIO *f, const char *string)
SSize_t    PerlIO_read        (PerlIO *f, void *vbuf,
                               Size_t count)
void       PerlIO_releaseFILE (PerlIO *f, FILE *stdio)
PerlIO *   PerlIO_reopen      (const char *path, const char *mode,
                               PerlIO *old)
void       PerlIO_rewind      (PerlIO *f)
int        PerlIO_seek        (PerlIO *f, Off_t offset,
                               int whence)
void       PerlIO_set_cnt     (PerlIO *f, SSize_t cnt)
void       PerlIO_set_ptrcnt  (PerlIO *f, STDCHAR *ptr,
                               SSize_t cnt)
void       PerlIO_setlinebuf  (PerlIO *f)
int        PerlIO_setpos      (PerlIO *f, SV *saved)
PerlIO *   PerlIO_stderr      (PerlIO *f, const char *mode,
                               const char *layers)
PerlIO *   PerlIO_stdin       (PerlIO *f, const char *mode,
                               const char *layers)
PerlIO *   PerlIO_stdout      (PerlIO *f, const char *mode,
                               const char *layers)
int        PerlIO_stdoutf     (const char *fmt, ...)
Off_t      PerlIO_tell        (PerlIO *f)
int        PerlIO_ungetc      (PerlIO *f, int ch)
SSize_t    PerlIO_unread      (PerlIO *f, const void *vbuf,
                               Size_t count)
int        PerlIO_vprintf     (PerlIO *f, const char *fmt,
                               va_list args)
SSize_t    PerlIO_write       (PerlIO *f, const void *vbuf,
                               Size_t count)
PERLIO_F_APPEND
PERLIO_F_CANREAD
PERLIO_F_CANWRITE
PERLIO_F_CRLF
PERLIO_F_EOF
PERLIO_F_ERROR
PERLIO_F_FASTGETS
PERLIO_F_LINEBUF
PERLIO_F_OPEN
PERLIO_F_RDBUF
PERLIO_F_TEMP
PERLIO_F_TRUNCATE
PERLIO_F_UNBUF
PERLIO_F_UTF8
PERLIO_F_WRBUF

Описание в perliol.

PERLIO_FUNCS_CAST

Преобразует указатель func к типу PerlIO_funcs *.

PERLIO_FUNCS_DECL

Объявляет ftab как таблицу функций PerlIO, то есть типа PerlIO_funcs. 

PERLIO_FUNCS_DECL(PerlIO * ftab)
PERLIO_K_BUFFERED
PERLIO_K_CANCRLF
PERLIO_K_FASTGETS
PERLIO_K_MULTIARG
PERLIO_K_RAW

Описание в perliol.

PERLIO_NOT_STDIO

Описание в perlapio.

PL_maxsysfd

Описание в perliol.

repeatcpy

Создаёт count копий len байт, начиная с адреса from, помещая их в память, начиная с адреса to, который должен быть достаточно велик, чтобы вместить все копии.

void  repeatcpy(char *to, const char *from, I32 len, IV count)
USE_STDIO

Описание в perlapio.

Целое число

CASTI32

Этот символ определён, если компилятор C может преобразовать отрицательные или большие числа с плавающей точкой в 32-битные целые числа.

HAS_INT64_T

Этот символ будет определён, если компилятор C поддерживает int64_t. Обычно для этого требуется подключение inttypes.h, но иногда достаточно sys/types.h.

HAS_LONG_LONG

Этот символ будет определён, если компилятор C поддерживает long long.

HAS_QUAD

Этот символ, если определён, указывает, что существует 64-битный целочисленный тип, Quad_t, и его беззнаковый аналог, Uquad_t. QUADKIND будет одним из QUAD_IS_INT, QUAD_IS_LONG, QUAD_IS_LONG_LONG, QUAD_IS_INT64_T, или QUAD_IS___INT64.

I32df

Этот символ определяет строку формата, используемую для вывода Perl I32 как целого десятичного числа со знаком.

INT16_C
INT32_C
INT64_C

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

Если на машине нет 64-битного типа, INT64_C не определено. Используйте "INTMAX_C" для получения максимального типа, доступного на платформе.

I16  INT16_C(number)
I32  INT32_C(number)
I64  INT64_C(number)
INTMAX_C

Возвращает токен, распознаваемый компилятором C, для константы number самого широкого целочисленного типа на машине. Например, если на машине есть long long, то INTMAX_C(-1) вернёт

-1LL

См. также, например, "INT32_C".

Используйте "IV" для объявления переменных максимального размера, используемого на данной платформе.

IV_MAX 
IV  IV_MAX
IV_MIN 
IV  IV_MIN
IVSIZE sizeof(IV) IVTYPE line_t LONGLONGSIZE LONGSIZE sizeof(long) memzero l *d 
void  memzero(void * d, Size_t l)
INTMAX_C(number)
INTSIZE

Этот символ содержит значение sizeof(int), чтобы препроцессор C мог принять решение, основываясь на нём.

I8SIZE

Этот символ содержит sizeof(I8).

I16SIZE

Этот символ содержит sizeof(I16).

I32SIZE

Этот символ содержит sizeof(I32).

I64SIZE

Этот символ содержит sizeof(I64).

I8TYPE

Этот символ определяет тип C, используемый для Perl's I8.

I16TYPE

Этот символ определяет тип C, используемый для Perl's I16.

I32TYPE

Этот символ определяет тип C, используемый для Perl's I32.

I64TYPE

Этот символ определяет тип C, используемый для Perl's I64.

IV
I8
I16
I32
I64

Описание в perlguts.

Наибольшее целое со знаком, которое помещается в IV на данной платформе.

Наименьшее целое со знаком, наиболее удалённое от 0, которое помещается в IV на данной платформе.

Этот символ содержит sizeof(IV).

Этот символ определяет тип C, используемый для Perl's IV.

Тип, используемый для объявления переменных, хранящих номера строк.

Этот символ содержит размер long long, чтобы препроцессор C мог принимать решения на основе него. Он определён только если система поддерживает long long.

Этот символ содержит значение sizeof(long), чтобы препроцессор C мог принимать решения на основе него.

Заполняет l байт, начиная с адреса *d, нулями.

PERL_INT_FAST8_T
PERL_INT_FAST16_T
PERL_UINT_FAST8_T
PERL_UINT_FAST16_T

Эти аналогичны соответствующим определениям типов C99 на платформах, где они существуют; они эквивалентны int и unsigned int на платформах, где их нет, так что вы можете использовать эти функции C99 в своём коде.

PERL_INT_MAX
PERL_INT_MIN
PERL_LONG_MAX
PERL_LONG_MIN
PERL_QUAD_MAX
PERL_QUAD_MIN
PERL_SHORT_MAX
PERL_SHORT_MIN
PERL_UCHAR_MAX
PERL_UCHAR_MIN
PERL_UINT_MAX
PERL_UINT_MIN
PERL_ULONG_MAX
PERL_ULONG_MIN
PERL_UQUAD_MAX
PERL_UQUAD_MIN
PERL_USHORT_MAX
PERL_USHORT_MIN

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

Для типов со знаком, наименьшее представимое число — это самое отрицательное число, наиболее удалённое от нуля.

Для компиляторов C99 и более поздних версий, эти значения соответствуют таким как INT_MAX, которые доступны в C-коде. Но эти константы, предоставляемые Perl, позволяют коду, скомпилированному на более ранних компиляторах, иметь доступ к тем же константам.

int             PERL_INT_MAX
int             PERL_INT_MIN
long            PERL_LONG_MAX
long            PERL_LONG_MIN
IV              PERL_QUAD_MAX
IV              PERL_QUAD_MIN
short           PERL_SHORT_MAX
short           PERL_SHORT_MIN
U8              PERL_UCHAR_MAX
U8              PERL_UCHAR_MIN
unsigned int    PERL_UINT_MAX
unsigned int    PERL_UINT_MIN
unsigned long   PERL_ULONG_MAX
unsigned long   PERL_ULONG_MIN
UV              PERL_UQUAD_MAX
UV              PERL_UQUAD_MIN
unsigned short  PERL_USHORT_MAX
unsigned short  PERL_USHORT_MIN
SHORTSIZE

Этот символ содержит значение sizeof(short), чтобы препроцессор C мог принимать решения на основе него.

UINT16_C
UINT32_C
UINT64_C

Возвращает токен, распознаваемый компилятором C, для константы number соответствующего беззнакового целочисленного типа на машине.

Если на машине нет 64-битного типа, UINT64_C не определено. Используйте "UINTMAX_C" для получения наибольшего доступного типа на платформе.

U16  UINT16_C(number)
U32  UINT32_C(number)
U64  UINT64_C(number)
UINTMAX_C

Возвращает токен, распознаваемый компилятором C, для константы number самого широкого беззнакового целочисленного типа на машине. Например, если машина имеет longs, UINTMAX_C(1) вернёт

1UL

См. также, например, "UINT32_C".

Используйте "UV" для объявления переменных максимального используемого размера на данной платформе.

UINTMAX_C(number)
U32of

Этот символ определяет строку формата, используемую для вывода Perl U32 как беззнакового восьмеричного целого числа.

U8SIZE

Этот символ содержит sizeof(U8).

U16SIZE

Этот символ содержит sizeof(U16).

U32SIZE

Этот символ содержит sizeof(U32).

U64SIZE

Этот символ содержит sizeof(U64).

U8TYPE

Этот символ определяет тип C, используемый для Perl's U8.

U16TYPE

Этот символ определяет тип C, используемый для Perl's U16.

U32TYPE

Этот символ определяет тип C, используемый для Perl's U32.

U64TYPE

Этот символ определяет тип C, используемый для Perl's U64.

U32uf

Этот символ определяет строку формата, используемую для вывода Perl U32 как беззнакового десятичного целого числа.

UV
U8
U16
U32
U64

Описание в perlguts.

UV_MAX

Наибольшее беззнаковое целое число, которое помещается в UV на этой платформе.

UV  UV_MAX
UV_MIN

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

UV  UV_MIN
UVSIZE

Этот символ содержит sizeof(UV).

UVTYPE

Этот символ определяет тип C, используемый для Perl's UV.

U32Xf

Этот символ определяет строку формата, используемую для вывода Perl U32 как беззнакового шестнадцатеричного целого числа в верхнем регистре ABCDEF.

U32xf

Этот символ определяет строку формата, используемую для вывода Perl U32 как беззнакового шестнадцатеричного целого числа в нижнем регистре abcdef.

WIDEST_UTYPE

Возвращает самый широкий беззнаковый целочисленный тип на платформе, в настоящее время либо U32 или U64. Это можно использовать в объявлениях, таких как

WIDEST_UTYPE my_uv;

или приведения типов

my_uv = (WIDEST_UTYPE) val;

Форматы ввода/вывода

Эти форматирования используются для форматирования соответствующего типа. Например, вместо

Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\n", iv);

используйте

Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\n", iv);

Это избавляет от необходимости знать, нужно ли, например, IV выводить как %d, %ld, или что-то ещё.

HvNAMEf

Описание в perlguts.

HvNAMEf_QUOTEDPREFIX

Описание в perlguts.

IVdf

Этот символ определяет строку формата, используемую для вывода Perl IV как знакового десятичного целого числа.

NVef

Этот символ определяет строку формата, используемую для вывода Perl NV в формате с плавающей точкой %e.

NVff

Этот символ определяет строку формата, используемую для вывода Perl NV в формате с плавающей точкой %f.

NVgf

Этот символ определяет строку формата, используемую для вывода Perl NV в формате с плавающей точкой %g.

PERL_PRIeldbl

Если определён, этот символ содержит строку, используемую stdio для форматирования длинных чисел с плавающей точкой (формат 'e') для вывода.

PERL_PRIfldbl

Если определён, этот символ содержит строку, используемую stdio для форматирования длинных чисел с плавающей точкой (формат 'f') для вывода.

PERL_PRIgldbl

Если определён, этот символ содержит строку, используемую stdio для форматирования длинных чисел с плавающей точкой (формат 'g') для вывода.

PERL_SCNfldbl

Если определён, этот символ содержит строку, используемую stdio для форматирования длинных чисел с плавающей точкой (формат 'f') для ввода.

PRINTF_FORMAT_NULL_OK

Разрешает, чтобы формат __printf__ был нулевым при проверке форматирования в стиле printf.

SVf

Описание в perlguts.

SVfARG

Описание в perlguts.

SVfARG(SV *sv)
SVf_QUOTEDPREFIX

Описание в perlguts.

UTF8f

Описание в perlguts.

UTF8fARG

Описание в perlguts.

UTF8fARG(bool is_utf8, Size_t byte_len, char *str)
UTF8f_QUOTEDPREFIX

Описание в perlguts.

UVf

DEPRECATED! Планируется удалить UVf из будущих релизов Perl. Не используйте его в новом коде; удалите его из существующего кода.

Устаревший вид UVuf, который следует заменить на

const char *  UVf
UVof

Этот символ определяет строку формата, используемую для вывода Perl UV как беззнакового восьмеричного целого числа.

UVuf

Этот символ определяет строку формата, используемую для вывода Perl UV как беззнакового десятичного целого числа.

UVXf

Этот символ определяет строку формата, используемую для вывода Perl UV как беззнакового шестнадцатеричного целого числа в верхнем регистре ABCDEF.

UVxf

Этот символ определяет строку формата, используемую для вывода Perl UV как беззнакового шестнадцатеричного целого числа в нижнем регистре abcdef.

Интерфейс лексического анализатора

Это нижний уровень парсера Perl, управляющий символами и токенами.

BHK

Описание в perlguts.

lex_bufutf8

ПРИМЕЧАНИЕ: lex_bufutf8 является экспериментальным и может измениться или быть удалён без предварительного уведомления.

Указывает, следует ли интерпретировать октеты в буфере лексического анализатора ("PL_parser->linestr") как UTF-8 кодирование Unicode символов. В противном случае они должны интерпретироваться как символы Latin-1. Это аналогично флагу SvUTF8 для скаляров.

В режиме UTF-8 не гарантируется, что буфер лексического анализатора фактически содержит валидный UTF-8. Код лексического анализа должен быть устойчив к невалидному кодированию.

Флаг SvUTF8 скаляра "PL_parser->linestr" значим, но не является единственным фактором, определяющим кодировку входных символов. Обычно при чтении файла скаляр содержит октеты и его флаг SvUTF8 выключен, но октеты должны интерпретироваться как UTF-8, если в силе прагма use utf8. Во время выполнения eval строки, у скаляра может быть включен флаг SvUTF8, и в этом случае его октеты должны интерпретироваться как UTF-8, если не в силе прагма use bytes. Эта логика может измениться в будущем; используйте эту функцию вместо самостоятельной реализации логики.

bool  lex_bufutf8()
lex_discard_to

ПРИМЕЧАНИЕ: lex_discard_to является экспериментальным и может измениться или быть удалён без предварительного уведомления.

Отбрасывает первую часть буфера "PL_parser->linestr" до ptr. Остальное содержимое буфера будет смещено, и все указатели в буфер будут обновлены соответствующим образом. ptr не должен находиться позже в буфере, чем позиция "PL_parser->bufptr": запрещается отбрасывать текст, который ещё не был проанализирован.

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

void  lex_discard_to(char *ptr)
lex_grow_linestr

ПРИМЕЧАНИЕ: lex_grow_linestr является экспериментальным и может измениться или быть удалён без предварительного уведомления.

Перевыделяет буфер лексического анализатора ("PL_parser->linestr"), чтобы вместить как минимум len октетов (включая завершающий NUL). Возвращает указатель на перевыделенный буфер. Это необходимо перед любым прямым изменением буфера, которое увеличит его длину. "lex_stuff_pvn" предлагает более удобный способ вставки текста в буфер.

Не используйте SvGROW или sv_grow напрямую с PL_parser->linestr; эта функция обновляет все переменные лексического анализатора, которые указывают непосредственно на буфер.

char *  lex_grow_linestr(STRLEN len)
lex_next_chunk

ПРИМЕЧАНИЕ: lex_next_chunk является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Считывает следующий фрагмент текста для лексерования, добавляя его к "PL_parser->linestr". Это следует вызывать, когда лексератор достиг конца текущего фрагмента и хочет получить больше данных. Обычно, но не обязательно, лексерование потребляет весь текущий фрагмент в этот момент.

Если "PL_parser->bufptr" указывает на самый конец текущего фрагмента (т.е., текущий фрагмент полностью потреблён), обычно текущий фрагмент удаляется одновременно со считыванием нового. Если flags имеет установленный LEX_KEEP_PREVIOUS бит, текущий фрагмент не будет удалён. Если текущий фрагмент не полностью потреблён, он не будет удалён, независимо от флага.

Возвращает true, если в буфер был добавлен новый текст, или false, если буфер достиг конца входного текста.

bool  lex_next_chunk(U32 flags)
lex_peek_unichar

ПРИМЕЧАНИЕ: lex_peek_unichar является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Предварительно просматривает один (Unicode) символ в тексте, который в настоящее время лексерится. Возвращает код символа (целое значение без знака) следующего символа или -1, если лексерование достигло конца входного текста. Чтобы обработать просмотренный символ, используйте "lex_read_unichar".

Если следующий символ находится в (или простирается в) следующий фрагмент входного текста, следующий фрагмент будет прочитан. Обычно текущий фрагмент будет удалён одновременно, но если flags имеет установленный LEX_KEEP_PREVIOUS бит, текущий фрагмент не будет удалён.

Если вход интерпретируется как UTF-8 и обнаружена ошибка кодировки UTF-8, генерируется исключение.

I32  lex_peek_unichar(U32 flags)
lex_read_space

ПРИМЕЧАНИЕ: lex_read_space является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Читает необязательные пробелы в стиле Perl в тексте, который в настоящее время лексерится. Пробелы могут включать обычные символы пробелов и пробелы в стиле Perl. #line директивы обрабатываются, если встречаются. "PL_parser->bufptr" перемещается мимо пробелов, чтобы он указывать на символ, не являющийся пробелом (или конец входного текста).

Если пробелы простираются в следующий фрагмент входного текста, следующий фрагмент будет прочитан. Обычно текущий фрагмент будет удалён одновременно, но если flags имеет установленный LEX_KEEP_PREVIOUS бит, текущий фрагмент не будет удалён.

void  lex_read_space(U32 flags)
lex_read_to

ПРИМЕЧАНИЕ: lex_read_to является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Потребляет текст в буфере лексера, от "PL_parser->bufptr" до ptr. Это перемещает "PL_parser->bufptr" для соответствия ptr, выполняя правильную обработку всякий раз, когда встречается символ новой строки. Это обычный способ потребления лексерованного текста.

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

void  lex_read_to(char *ptr)
lex_read_unichar

ПРИМЕЧАНИЕ: lex_read_unichar является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Читает следующий (Unicode) символ в тексте, который в настоящее время лексерится. Возвращает код символа (целое значение без знака) прочитанного символа и перемещает "PL_parser->bufptr" мимо символа или возвращает -1, если лексерование достигло конца входного текста. Чтобы неразрушающим образом проверить следующий символ, используйте "lex_peek_unichar" вместо этого.

Если следующий символ находится в (или простирается в) следующий фрагмент входного текста, следующий фрагмент будет прочитан. Обычно текущий фрагмент будет удалён одновременно, но если flags имеет установленный LEX_KEEP_PREVIOUS бит, текущий фрагмент не будет удалён.

Если вход интерпретируется как UTF-8 и обнаружена ошибка кодировки UTF-8, генерируется исключение.

I32  lex_read_unichar(U32 flags)
lex_start

ПРИМЕЧАНИЕ: lex_start является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Создаёт и инициализирует новый объект состояния лексера/парсера, предоставляя контекст для лексерования и разбора нового источника кода Perl. Указатель на новый объект состояния помещается в "PL_parser". В стек сохранения вносится запись, чтобы при развёртывании новый объект состояния был уничтожен, а предыдущее значение "PL_parser" было восстановлено. Для очистки контекста разбора ничего больше делать не нужно.

Парсируемый код поступает из line и rsfp. line, если не равно нулю, предоставляет строку (в форме SV) содержащую код для парсинга. Создаётся копия строки, поэтому последующие изменения line не влияют на парсинг. rsfp, если не равно нулю, предоставляет поток ввода, из которого будет читаться код для парсинга. Если оба значения не равны нулю, код в line обрабатывается в первую очередь и должен состоять из полных строк ввода, а rsfp предоставляет остальную часть исходного кода.

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

void  lex_start(SV *line, PerlIO *rsfp, U32 flags)
lex_stuff_pv

ПРИМЕЧАНИЕ: lex_stuff_pv является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Вставляет символы в буфер лексера ("PL_parser->linestr") сразу после текущей точки лексерования ("PL_parser->bufptr"), перевыделяя буфер при необходимости. Это означает, что код лексерования, который выполняется позже, увидит символы так, как будто они появились в исходном коде. Не рекомендуется делать это в процессе обычного парсинга, и большинство случаев использования этой функции рискуют быть интерпретированными нежелательным образом.

Строка, которая должна быть вставлена, представлена байтами, начинающимися в pv и продолжающимися до первого нуля. Эти байты интерпретируются как UTF-8 или Latin-1, в зависимости от того, установлен ли LEX_STUFF_UTF8 флаг в flags. Символы кодируются для буфера лексера в соответствии с текущей интерпретацией буфера ("lex_bufutf8"). Если неудобно завершать строку, подлежащую вставке, нулём, функция "lex_stuff_pvn" более подходяща.

void  lex_stuff_pv(const char *pv, U32 flags)
lex_stuff_pvn

ПРИМЕЧАНИЕ: lex_stuff_pvn является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Вставляет символы в буфер лексера ("PL_parser->linestr") сразу после текущей точки лексерования ("PL_parser->bufptr"), перевыделяя буфер при необходимости. Это означает, что код лексерования, который выполняется позже, увидит символы так, как будто они появились в исходном коде. Не рекомендуется делать это в процессе обычного парсинга, и большинство случаев использования этой функции рискуют быть интерпретированными нежелательным образом.

Строка, подлежащая вставке, представлена len байтами, начинающимися в pv. Эти байты интерпретируются как UTF-8 или Latin-1, в зависимости от того, установлен ли LEX_STUFF_UTF8 флаг в flags. Символы кодируются для буфера лексера в соответствии с текущей интерпретацией буфера ("lex_bufutf8"). Если строка, подлежащая вставке, доступна как скаляр Perl, функция "lex_stuff_sv" более удобна.

void  lex_stuff_pvn(const char *pv, STRLEN len, U32 flags)
lex_stuff_pvs

ПРИМЕЧАНИЕ: lex_stuff_pvs является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Аналогично "lex_stuff_pvn", но принимает строку вместо пары строка/длина.

void  lex_stuff_pvs("pv", U32 flags)
lex_stuff_sv

ПРИМЕЧАНИЕ: lex_stuff_sv является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Вставляет символы в буфер лексера ("PL_parser->linestr") сразу после текущей точки лексерования ("PL_parser->bufptr"), перевыделяя буфер при необходимости. Это означает, что код лексерования, который выполняется позже, увидит символы так, как будто они появились в исходном коде. Не рекомендуется делать это в процессе обычного парсинга, и большинство случаев использования этой функции рискуют быть интерпретированными нежелательным образом.

Строка, которая должна быть вставлена, - это строковое значение sv. Символы кодируются для буфера лексера в соответствии с текущей интерпретацией буфера ("lex_bufutf8"). Если строка, подлежащая вставке, не является скаляром Perl, функция "lex_stuff_pvn" позволяет избежать необходимости создавать скаляр.

void  lex_stuff_sv(SV *sv, U32 flags)
lex_unstuff

ПРИМЕЧАНИЕ: lex_unstuff является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Удаляет текст, который собирается быть лексерованным, от "PL_parser->bufptr" до ptr. Текст, следующий за ptr, будет перемещён, а буфер сокращён. Это скрывает удалённый текст от любого кода лексерования, который выполняется позже, как если бы текст никогда не появлялся.

Это не стандартный способ потребления лексерованного текста. Для этого используйте "lex_read_to".

void  lex_unstuff(char *ptr)
END_OF_DOCUMENT_MARKER
parse_arithexpr

ПРИМЕЧАНИЕ: parse_arithexpr является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Разбор арифметического выражения Perl. Оно может содержать операторы с приоритетом до битовых сдвигов. Выражение должно быть завершено оператором сравнения или оператором с более низким приоритетом, или чем-либо, что обычно завершает выражение, например, точкой с запятой. Если у flags установлен бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае оно обязательно. Вызывающая функция должна гарантировать, что динамическое состояние парсера ("PL_parser" и т.д.) правильно отражает источник анализируемого кода и лексический контекст для выражения.

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

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

OP *  parse_arithexpr(U32 flags)
parse_barestmt

ПРИМЕЧАНИЕ: parse_barestmt является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Разбор одного простого оператора Perl. Это может быть обычный оператор-команда или объявление с эффектом во время компиляции. Он не включает метки или другие приставки. Вызывающая функция должна гарантировать, что динамическое состояние парсера ("PL_parser" и т.д.) правильно отражает источник анализируемого кода и лексический контекст для оператора.

Возвращается дерево операций, представляющее оператор. Может быть нулевым указателем, если оператор пустой, например, если это было определение подпрограммы (которая имеет побочные эффекты во время компиляции). Если не нулевой, он будет содержать непосредственно операторы, реализующие оператор, подходящие для передачи в "newSTATEOP". Он обычно не будет включать оператор nextstate или эквивалентный (за исключением тех, которые вложены в область, полностью содержащуюся внутри оператора).

Параметр flags зарезервирован для будущего использования и всегда должен быть равен нулю.

OP *  parse_barestmt(U32 flags)
parse_block

ПРИМЕЧАНИЕ: parse_block является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Разбор одного полного блока кода Perl. Он состоит из открывающей фигурной скобки, последовательности операторов и закрывающей фигурной скобки. Блок представляет собой лексическую область, поэтому переменные my и различные эффекты во время компиляции могут быть заключены в нём. Вызывающая функция должна гарантировать, что динамическое состояние парсера ("PL_parser" и т.д.) правильно отражает источник анализируемого кода и лексический контекст для оператора.

Возвращается дерево операций, представляющее блок кода. Это всегда реальный оператор, никогда не нулевой указатель. Он обычно будет списком lineseq, включая операторы nextstate или эквивалентные. Операторы для построения каких-либо видов областей выполнения не включаются из-за того, что это блок.

Если при разборе или компиляции произошла ошибка, в большинстве случаев возвращается корректное дерево операций (вероятно, нулевой указатель). Ошибка отражается в состоянии парсера, обычно приводя к одному исключению на верхнем уровне разбора, которое охватывает все произошедшие ошибки компиляции. Однако некоторые ошибки компиляции могут вызвать исключение немедленно.

Параметр flags зарезервирован для будущего использования и всегда должен быть равен нулю.

OP *  parse_block(U32 flags)
parse_fullexpr

ПРИМЕЧАНИЕ: parse_fullexpr является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Разбор одного полного выражения Perl. Это позволяет использовать всю грамматику выражений, включая операторы с самым низким приоритетом, такие как or. Выражение должно быть завершено токеном, которым обычно завершается выражение: конец файла, закрывающая скобка, точка с запятой или ключевое слово, указывающее модификатор оператора постфиксного выражения. Если у flags установлен бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае оно обязательно. Вызывающая функция должна гарантировать, что динамическое состояние парсера ("PL_parser" и т.д.) правильно отражает источник анализируемого кода и лексический контекст для выражения.

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

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

OP *  parse_fullexpr(U32 flags)
parse_fullstmt

ПРИМЕЧАНИЕ: parse_fullstmt является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Разбор одного полного оператора Perl. Это может быть обычный оператор-команда или объявление с эффектом во время компиляции, а также может включать необязательные метки. Вызывающая функция должна гарантировать, что динамическое состояние парсера ("PL_parser" и т.д.) правильно отражает источник анализируемого кода и лексический контекст для оператора.

Возвращается дерево операций, представляющее оператор. Может быть нулевым указателем, если оператор пустой, например, если это было определение подпрограммы (которая имеет побочные эффекты во время компиляции). Если не нулевой, он будет результатом вызова "newSTATEOP", обычно включающим оператор nextstate или эквивалентный.

Если при разборе или компиляции произошла ошибка, в большинстве случаев возвращается корректное дерево операций (вероятно, нулевой указатель). Ошибка отражается в состоянии парсера, обычно приводя к одному исключению на верхнем уровне разбора, которое охватывает все произошедшие ошибки компиляции. Однако некоторые ошибки компиляции могут вызвать исключение немедленно.

Параметр flags зарезервирован для будущего использования и всегда должен быть равен нулю.

OP *  parse_fullstmt(U32 flags)
parse_label

ПРИМЕЧАНИЕ: parse_label является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Разбор одной метки, возможно необязательной, типа, которая может предварять оператор Perl. Вызывающая функция должна гарантировать, что динамическое состояние парсера ("PL_parser" и т.д.) правильно отражает источник анализируемого кода. Если у flags установлен бит PARSE_OPTIONAL, то метка является необязательной, в противном случае она обязательна.

Имя метки возвращается в виде нового скаляра. Если необязательная метка отсутствует, возвращается нулевой указатель.

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

SV *  parse_label(U32 flags)
parse_listexpr

ПРИМЕЧАНИЕ: parse_listexpr является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Разбор выражения списка Perl. Оно может содержать операторы с приоритетом до оператора запятой. Выражение должно быть завершено оператором с низким приоритетом, таким как or, или чем-либо, что обычно завершает выражение, например, точкой с запятой. Если у flags установлен бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае оно обязательно. Вызывающая функция должна гарантировать, что динамическое состояние парсера ("PL_parser" и т.д.) правильно отражает источник анализируемого кода и лексический контекст для выражения.

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

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

OP *  parse_listexpr(U32 flags)
parse_stmtseq

ПРИМЕЧАНИЕ: parse_stmtseq является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Разбор последовательности нуля или более операторов Perl. Они могут быть обычными операторами-командами, включая необязательные метки, или объявлениями с эффектом во время компиляции, или любой их комбинацией. Последовательность операторов заканчивается, когда встречается закрывающая фигурная скобка или конец файла в месте, где новый оператор мог бы быть допустимым. Вызывающая функция должна гарантировать, что динамическое состояние парсера ("PL_parser" и т.д.) правильно отражает источник анализируемого кода и лексический контекст для операторов.

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

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

Параметр flags зарезервирован для будущего использования и всегда должен быть равен нулю.

OP *  parse_stmtseq(U32 flags)
parse_subsignature

ПРИМЕЧАНИЕ: parse_subsignature является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Разбор объявления подписи подпрограммы. Это содержимое скобок, следующих за именем или анонимным объявлением подпрограммы, когда функция signatures включена. Обратите внимание, что эта функция не ожидает и не потребляет открывающие и закрывающие скобки вокруг подписи; обработка этих скобок лежит на ответственности вызывающей функции.

Эта функция должна вызываться только во время разбора подпрограммы; после вызова «start_subparse». Она может выделять лексические переменные на стеке для текущей подпрограммы.

Дерево операций для распаковки аргументов со стека во время выполнения возвращается. Это дерево операций должно появляться в начале скомпилированной функции. Вызывающая функция может использовать «op_append_list» для построения тела своей функции после него или объединить его с телом перед вызовом «newATTRSUB».

Параметр flags зарезервирован для использования в будущем и должен всегда быть нулём.

OP *  parse_subsignature(U32 flags)
parse_termexpr

ПРИМЕЧАНИЕ: parse_termexpr является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Разбор выражения Perl. Оно может содержать операторы с приоритетом до операторов присваивания. Выражение должно быть завершено (и, следовательно, закончено) либо запятой, либо оператором с более низким приоритетом, либо чем-либо, что обычно завершает выражение, например, точкой с запятой. Если flags имеет установленный бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае — обязательным. Вызывающая функция должна гарантировать, что динамическое состояние парсера («PL_parser» и т. д.) правильно настроен для отражения источника разделяемого кода и лексического контекста для выражения.

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

Если при разборе или компиляции произошла ошибка, в большинстве случаев возвращается допустимое дерево операций. Об ошибке сообщается в состоянии парсера, обычно приводя к одному исключению на верхнем уровне разбора, которое охватывает все ошибки компиляции, произошедшие. Однако некоторые ошибки компиляции вызовут исключение немедленно.

OP *  parse_termexpr(U32 flags)
PL_parser

Указатель на структуру, описывающую состояние текущей операции разбора. Указатель можно локально изменить, чтобы выполнить вложенный разбор, не вмешиваясь в состояние внешнего разбора. Отдельные члены PL_parser имеют свою документацию.

PL_parser->bufend

ПРИМЕЧАНИЕ: PL_parser->bufend является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Прямой указатель на конец фрагмента текста, который в настоящее время лексически анализируется, конец буфера лексического анализатора. Это равно SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr). Символ NUL (нулевой байт) всегда расположен в конце буфера и не считается частью содержимого буфера.

PL_parser->bufptr

ПРИМЕЧАНИЕ: PL_parser->bufptr является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Указывает на текущую позицию лексического анализа в буфере лексического анализатора. Символы вокруг этой точки могут свободно проверяться в пределах диапазона, ограниченного SvPVX("PL_parser->linestr") и «PL_parser->bufend». Байты буфера могут быть предназначены для интерпретации как UTF-8 или Latin-1, как указано в «lex_bufutf8».

Код лексического анализа (будь то в ядре Perl или нет) перемещает этот указатель мимо потребляемых символов. Ожидается, что он также выполнит некоторые бухгалтерские операции всякий раз, когда потребляется символ новой строки. Это перемещение можно более удобно выполнить с помощью функции «lex_read_to», которая должным образом обрабатывает новые строки.

Интерпретацию байтов буфера можно абстрагировать, используя несколько более высокие функции уровня «lex_peek_unichar» и «lex_read_unichar».

PL_parser->linestart

ПРИМЕЧАНИЕ: PL_parser->linestart является экспериментальным и может быть изменён или удалён без предварительного уведомления.

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

PL_parser->linestr

ПРИМЕЧАНИЕ: PL_parser->linestr является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Скаляр буфера, содержащий фрагмент текста, который в настоящее время рассматривается лексическим анализатором. Это всегда простой строковый скаляр (для которого SvPOK является истинным). Он не предназначен для использования как скаляр обычным способом скалярных операций; вместо этого обратитесь к буферу непосредственно через переменные-указатели, описанные ниже.

Лексический анализатор поддерживает различные указатели char* на вещи в буфере PL_parser->linestr. Если буфер PL_parser->linestr будет перераспределён, все эти указатели необходимо будет обновить. Не пытайтесь делать это вручную, а используйте «lex_grow_linestr», если вам нужно перераспределить буфер.

Содержимое фрагмента текста в буфере обычно точно соответствует одной полной строке входных данных, включая символ новой строки, но существуют ситуации, когда это не так. Байты буфера могут быть предназначены для интерпретации как UTF-8 или Latin-1. Функция «lex_bufutf8» сообщает вам, какой из них. Не используйте флаг SvUTF8 на этом скаляре, который может с ним не совпадать.

Для прямой проверки буфера переменная «PL_parser->bufend» указывает на конец буфера. Текущая позиция лексического анализатора указана переменной «PL_parser->bufptr». Прямое использование этих указателей обычно предпочтительнее, чем проверка скаляра обычным способом скалярных операций.

suspend_compcv

Реализует часть концепции «подвешенного CV компиляции», который можно использовать для приостановки парсера и компилятора во время разбора CV, чтобы вернуться к нему позже.

Эта функция сохраняет текущее состояние компилируемой подпрограммы (PL_compcv) в предоставленный буфер. Это должно использоваться первоначально для создания состояния в буфере, как окончательная вещь перед LEAVE внутри блока.

ENTER;
start_subparse(0);
...

suspend_compcv(&buffer);
LEAVE;

После приостановки функции resume_compcv или resume_compcv_and_save можно использовать для продолжения разбора с точки, на которой он остановился.

void  suspend_compcv(struct suspended_compcv *buffer)
wrap_infix_plugin

ПРИМЕЧАНИЕ: wrap_infix_plugin является экспериментальным и может быть изменён или удалён без предварительного уведомления.

ПРИМЕЧАНИЕ: Этот API существует исключительно для обеспечения работы модуля CPAN XS::Parse::Infix. Не ожидается, что дополнительные модули будут использовать его; скорее, они должны использовать XS::Parse::Infix для обеспечения разбора новых инфиксных операторов.

Добавляет функцию C в цепочку инфиксных плагинов. Это предпочтительный способ управления переменной «PL_infix_plugin». new_plugin — указатель на функцию C, которая должна быть добавлена в цепочку инфиксных плагинов, а old_plugin_p указывает на место хранения указателя на следующую функцию в цепочке. Значение new_plugin записывается в переменную «PL_infix_plugin», а ранее сохранённое там значение — в *old_plugin_p.

Прямого доступа к «PL_infix_plugin» следует избегать.

void  wrap_infix_plugin(Perl_infix_plugin_t new_plugin,
                        Perl_infix_plugin_t *old_plugin_p)
wrap_keyword_plugin

ПРИМЕЧАНИЕ: wrap_keyword_plugin является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Добавляет функцию C в цепочку плагинов ключевых слов. Это предпочтительный способ управления переменной «PL_keyword_plugin». new_plugin — указатель на функцию C, которая должна быть добавлена в цепочку плагинов ключевых слов, а old_plugin_p указывает на место хранения указателя на следующую функцию в цепочке. Значение new_plugin записывается в переменную «PL_keyword_plugin», а ранее сохранённое там значение — в *old_plugin_p.

«PL_keyword_plugin» является глобальной для всего процесса, и модуль, желающий подключиться к разбору ключевых слов, может быть вызван более одного раза на процесс, обычно в разных потоках. Чтобы справиться с этой ситуацией, эта функция идемпотентна. Место *old_plugin_p первоначально (один раз на процесс) должно содержать нулевой указатель. Переменная C статической длины (объявленная на уровне файла, как правило, также помеченная static для обеспечения внутренней связи) будет неявно инициализирована должным образом, если у неё нет явного инициализатора. Эта функция будет фактически изменять цепочку плагинов только в том случае, если она найдёт *old_plugin_p равным нулю. Эта функция также потокобезопасна в небольших масштабах. Она использует соответствующую блокировку, чтобы избежать гонок при доступе к «PL_keyword_plugin».

Когда эта функция вызывается, функция, на которую ссылается new_plugin, должна быть готова к вызову, за исключением *old_plugin_p, которое не заполнено. В ситуациях с многопоточностью new_plugin может быть вызвана немедленно, даже прежде чем эта функция вернётся. *old_plugin_p всегда будет правильно установлено до вызова new_plugin. Если new_plugin решит ничего не делать со специальным идентификатором, который ему передаётся (что обычно бывает в большинстве вызовов плагина ключевого слова), он должен перенаправить функцию плагина, на которую ссылается *old_plugin_p.

Взяв всё вместе, код XS для установки плагина ключевого слова обычно выглядит примерно так:

static Perl_keyword_plugin_t next_keyword_plugin;
static OP *my_keyword_plugin(pTHX_
    char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
{
    if (memEQs(keyword_ptr, keyword_len,
               "my_new_keyword")) {
        ...
    } else {
        return next_keyword_plugin(aTHX_
            keyword_ptr, keyword_len, op_ptr);
    }
}
BOOT:
    wrap_keyword_plugin(my_keyword_plugin,
                        &next_keyword_plugin);

Прямого доступа к «PL_keyword_plugin» следует избегать.

void  wrap_keyword_plugin(Perl_keyword_plugin_t new_plugin,
                          Perl_keyword_plugin_t *old_plugin_p)

Локали

DECLARATION_FOR_LC_NUMERIC_MANIPULATION

Этот макрос должен использоваться как утверждение. Он объявляет частную переменную (название которой начинается с нижнего подчёркивания), необходимую другим макросам в этой секции. Неправильное включение этого макроса должно приводить к синтаксической ошибке. Для совместимости с компиляторами C89 C его следует поместить в блок перед любыми исполняемыми операторами.

void  DECLARATION_FOR_LC_NUMERIC_MANIPULATION
foldEQ_locale

Возвращает true, если первые len байта строк s1 и s2 одинаковы без учёта регистра в текущей локали; в противном случае — false.

I32  foldEQ_locale(const char *a, const char *b, I32 len)
HAS_DUPLOCALE

Этот символ, если он определён, указывает, что процедура duplocale доступна для дублирования объекта локали.

END_OF_DOCUMENT_MARKER
HAS_FREELOCALE

Этот символ, если определён, указывает, что функция freelocale доступна для освобождения ресурсов, связанных с объектом локали.

HAS_LC_MONETARY_2008

Этот символ, если определён, указывает, что функция localeconv доступна и имеет дополнительные члены, добавленные в POSIX 1003.1-2008.

HAS_LOCALECONV

Этот символ, если определён, указывает, что функция localeconv доступна для числового и денежного форматирования.

HAS_LOCALECONV_L

Этот символ, если определён, указывает, что функция localeconv_l доступна для запроса определённой информации о локали.

HAS_NEWLOCALE

Этот символ, если определён, указывает, что функция newlocale доступна для возвращения нового объекта локали или изменения существующего объекта локали.

HAS_NL_LANGINFO

Этот символ, если определён, указывает, что функция nl_langinfo доступна для возвращения данных локали. Вам также потребуется langinfo.h и, следовательно, I_LANGINFO.

HAS_NL_LANGINFO_L

Этот символ, при определении, указывает на наличие функции nl_langinfo_l()

HAS_QUERYLOCALE

Этот символ, если определён, указывает, что функция querylocale доступна для возвращения имени локали для маски категории.

HAS_SETLOCALE

Этот символ, если определён, указывает, что функция setlocale доступна для обработки реализаций ctype, специфичных для локали.

HAS_SETLOCALE_R

Этот символ, если определён, указывает, что функция setlocale_r доступна для установоки локали с поддержкой повторного входа.

HAS_THREAD_SAFE_NL_LANGINFO_L

Этот символ, при определении, указывает на наличие функции nl_langinfo_l(), и что она потокобезопасна.

HAS_USELOCALE

Этот символ, если определён, указывает, что функция uselocale доступна для установки текущей локали для потока вызова.

I_LANGINFO

Этот символ, если определён, указывает, что langinfo.h существует и должен быть включён.

#ifdef I_LANGINFO
    #include <langinfo.h>
#endif
I_LOCALE

Этот символ, если определён, указывает C-программе, что она должна включить locale.h.

#ifdef I_LOCALE
    #include <locale.h>
#endif
IN_LOCALE

Принимает значение TRUE, если действует псевдо-pragma локали без параметра (use locale).

bool  IN_LOCALE
IN_LOCALE_COMPILETIME

Принимает значение TRUE, если при компиляции Perl-программы (включая eval) действует псевдо-pragma локали без параметра (use locale).

bool  IN_LOCALE_COMPILETIME
IN_LOCALE_RUNTIME

Принимает значение TRUE, если при выполнении Perl-программы (включая eval) действует псевдо-pragma локали без параметра (use locale).

bool  IN_LOCALE_RUNTIME
I_XLOCALE

Этот символ, если определён, указывает C-программе, что заголовок xlocale.h доступен. См. также "NEED_XLOCALE_H"

#ifdef I_XLOCALE
    #include <xlocale.h>
#endif
NEED_XLOCALE_H

Этот символ, если определён, указывает C-программе, что она должна включить xlocale.h, чтобы получить newlocale() и его аналоги.

Perl_langinfo
Perl_langinfo8

Perl_langinfo является (почти) прямым заменителем системной функции nl_langinfo(3), принимающей те же item параметры и возвращающей ту же информацию. Но она более потокобезопасна, чем обычная nl_langinfo(), скрывает особенности обработки локали в Perl от вашего кода и может использоваться на системах, где отсутствует встроенная nl_langinfo.

Однако, следует использовать улучшенную версию: "Perl_langinfo8", которая ведет себя идентично, за исключением дополнительного параметра, указателя на переменную, объявленную как "utf8ness_t", в которую она возвращает информацию о том, как следует обрабатывать возвращаемую строку, с точки зрения кодировки UTF-8 или нет.

Об отличиях от обычной nl_langinfo():

a.

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

b.

Они возвращают правильные результаты для RADIXCHAR и THOUSEP элементов, без необходимости написания дополнительного кода. Причина дополнительного кода в том, что они относятся к категории локали LC_NUMERIC, которая в Perl обычно устанавливается так, что разделитель десятичных знаков — точка, а разделитель — пустая строка, независимо от предполагаемой локали, и для получения ожидаемых результатов необходимо временно переключиться в основную локаль и затем вернуться обратно. (Можно использовать обычные nl_langinfo и "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING", но тогда вы не получите других преимуществ Perl_langinfo(); отсутствие сохранения LC_NUMERIC в C (или эквивалентной) локали нарушит многие модули CPAN, ожидающие, что символ десятичного разделителя будет точкой.)

c.

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

d.

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

e.

Но самое главное, они работают на системах без nl_langinfo, таких как Windows, что делает ваш код более переносимым. Из примерно пятидесяти возможных элементов, определённых стандартом POSIX 2008, http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html, только один полностью не реализован, хотя на платформах, не являющихся Windows, ещё один существенный элемент не полностью реализован). Они используют различные методы для восстановления других элементов, включая вызовы localeconv(3) и strftime(3), которые определены в C89, поэтому всегда должны быть доступны. Более поздние версии strftime() имеют дополнительные возможности; то, что возвращает C-локаль или "", возвращается для любого элемента, недоступного на вашей системе.

Важно отметить, что при вызове с элементом, восстановленным с помощью localeconv, буфер из любого предыдущего явного вызова localeconv(3) будет перезаписан. Но вы не должны использовать localeconv , поскольку он не является потокобезопасным и имеет те же проблемы, которые описаны в пункте 'b.' выше, для полей, возвращаемых категорией локали LC_NUMERIC. Вместо этого, избегайте всех этих проблем, вызывая "Perl_localeconv", который потокобезопасен; или используя методы из perlcall для вызова POSIX::localeconv(), который также потокобезопасен.

Подробности по тем элементам, которые могут отличаться от того, что возвращает эта эмуляция, и от того, что вернёт встроенная nl_langinfo(), описаны в I18N::Langinfo.

При использовании Perl_langinfo8 (или обычного Perl_langinfo) на системах без встроенной nl_langinfo(), вы должны

#include "perl_langinfo.h"

перед perl.h #include. Вы можете заменить ваше langinfo.h #include на этот. (Такой способ исключает символы, которые обычный langinfo.h попытается импортировать в пространство имён для кода, которому это не нужно.)

const char *  Perl_langinfo (const int item)
const char *  Perl_langinfo8(const int item, utf8ness_t *utf8ness)
Perl_localeconv

Это потокобезопасная версия libc localeconv(3). Она эквивалентна POSIX::localeconv (возвращающей хеш с localeconv() полями), но прямо вызываема из XS-кода.

HV *  Perl_localeconv(pTHX)
Perl_setlocale

Это (почти) полная замена системной функции setlocale(3), принимающая те же параметры и возвращающая ту же информацию, за исключением того, что она возвращает правильный базовый LC_NUMERIC локали. Обычная функция setlocale вместо этого вернёт C если базовая локали имеет символ десятичной точки, отличный от точки, или непустой разделитель тысяч для отображения чисел с плавающей точкой. Это происходит потому, что perl сохраняет эту категорию локали таким образом, что у неё точка и пустой разделитель, временно изменяя локаль во время операций, где требуется базовая. Perl_setlocale знает об этом и компенсирует; обычная setlocale функция — нет.

Ещё одна причина, по которой это не полная замена, заключается в том, что она объявлена возвращающей const char *, в то время как системная setlocale опускает const (предположительно потому, что её API был определён давно и не может быть обновлён; изменять информацию, которую setlocale возвращает, запрещено; попытка этого приводит к segfaults).

Наконец, Perl_setlocale работает во всех случаях, тогда как обычная функция setlocale может быть совершенно неэффективной на некоторых платформах в некоторых конфигурациях.

Изменение локали не является хорошей идеей, когда работает более одного потока, за исключением систем, где предопределённая переменная ${^SAFE_LOCALES} равна 1. Это происходит потому, что на таких системах локали глобальна для всего процесса, а не только для потока, вызывающего функцию. Таким образом, изменение в одном потоке мгновенно изменяет её во всех. На некоторых таких системах системная функция setlocale() неэффективна, возвращает неправильную информацию и не изменяет локаль фактически. z/OS отказывается пытаться изменить локаль после создания второго потока. Perl_setlocale, должна дать вам точные результаты того, что фактически произошло на этих проблемных платформах, возвращая NULL, если система запретила изменение локали.

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

const char *  Perl_setlocale(const int category,
                             const char *locale)
RESTORE_LC_NUMERIC

Используется совместно с одним из макросов "STORE_LC_NUMERIC_SET_TO_NEEDED" и "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" для надлежащего восстановления состояния LC_NUMERIC.

Для объявления в процессе компиляции приватной переменной, используемой этим макросом и двумя макросами STORE, должен быть вызов "DECLARATION_FOR_LC_NUMERIC_MANIPULATION". Этот макрос должен вызываться как отдельное утверждение, а не выражение, но с пустым списком аргументов, например:

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   RESTORE_LC_NUMERIC();
    ...
}
void  RESTORE_LC_NUMERIC()
SETLOCALE_ACCEPTS_ANY_LOCALE_NAME

Если этот символ определён, это означает, что функция setlocale доступна и принимает любые имена локали в качестве допустимых.

STORE_LC_NUMERIC_FORCE_TO_UNDERLYING

Используется кодом XS, который LC_NUMERIC учитывает локаль, чтобы установить локаль для категории LC_NUMERIC на то, что perl считает текущей базовой локалью. (Интерпретатор perl может ошибаться относительно фактической базовой локали, если какой-то код C или XS вызывал функцию C-библиотеки setlocale(3) в скрытом режиме; вызов "sync_locale" перед вызовом этого макроса обновит записи perl).

Для объявления в процессе компиляции приватной переменной, используемой этим макросом, должен быть вызов "DECLARATION_FOR_LC_NUMERIC_MANIPULATION". Этот макрос должен вызываться как отдельное утверждение, а не выражение, но с пустым списком аргументов, например:

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
    ...
   RESTORE_LC_NUMERIC();
    ...
}

Приватная переменная используется для сохранения текущего состояния локали, чтобы соответствующий вызов макроса "RESTORE_LC_NUMERIC" мог восстановить его.

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

void  STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
STORE_LC_NUMERIC_SET_TO_NEEDED

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

Этот макрос гарантирует, что текущее состояние LC_NUMERIC установлено должным образом, чтобы учитывать локаль, если вызов кода XS или C из Perl-программы происходит в рамках области use locale; или игнорировать локаль, если вызов происходит вне этой области.

Этот макрос является началом оболочки кода C или XS; завершение оболочки выполняется вызовом макроса "RESTORE_LC_NUMERIC" после операции. В противном случае состояние может быть изменено, что отрицательно повлияет на другой код XS.

Для объявления в процессе компиляции приватной переменной, используемой этим макросом, должен быть вызов "DECLARATION_FOR_LC_NUMERIC_MANIPULATION". Этот макрос должен вызываться как отдельное утверждение, а не выражение, но с пустым списком аргументов, например:

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   STORE_LC_NUMERIC_SET_TO_NEEDED();
    ...
   RESTORE_LC_NUMERIC();
    ...
}

В многопоточных perl-интерпретаторах, не работающих с потокобезопасной функциональностью, этот макрос использует мьютекс для принудительного создания критической секции. Поэтому соответствующий макрос RESTORE должен быть рядом и гарантированно вызван; см. "WITH_LC_NUMERIC_SET_TO_NEEDED" для более контролируемого способа обеспечения этого.

void  STORE_LC_NUMERIC_SET_TO_NEEDED()
STORE_LC_NUMERIC_SET_TO_NEEDED_IN

Аналогично "STORE_LC_NUMERIC_SET_TO_NEEDED", с in_lc_numeric, предоставленным как предварительно вычисленное значение IN_LC(LC_NUMERIC). Ответственность вызывающего кода — гарантировать, что состояние PL_compiling и PL_hints не изменилось с момента предварительного вычисления.

void  STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric)
WITH_LC_NUMERIC_SET_TO_NEEDED

Этот макрос вызывает указанное утверждение или блок в контексте пары "STORE_LC_NUMERIC_SET_TO_NEEDED" .. "RESTORE_LC_NUMERIC", если это необходимо, например:

WITH_LC_NUMERIC_SET_TO_NEEDED(
  SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
);

эквивалентно:

{
#ifdef USE_LOCALE_NUMERIC
  DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
  STORE_LC_NUMERIC_SET_TO_NEEDED();
#endif
  SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
#ifdef USE_LOCALE_NUMERIC
  RESTORE_LC_NUMERIC();
#endif
}
void  WITH_LC_NUMERIC_SET_TO_NEEDED(block)
WITH_LC_NUMERIC_SET_TO_NEEDED_IN

Аналогично "WITH_LC_NUMERIC_SET_TO_NEEDED", с in_lc_numeric, предоставленным как предварительно вычисленное значение IN_LC(LC_NUMERIC). Ответственность вызывающего кода — гарантировать, что состояние PL_compiling и PL_hints не изменилось с момента предварительного вычисления.

void  WITH_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric, block)

Магия

"Магия" — это особые данные, прикреплённые к структурам SV, чтобы придать им "волшебные" свойства. Когда любой Perl-код пытается прочитать или записать в SV, отмеченный как магический, он вызывает функцию 'get' или 'set', связанную с этой магией SV. get вызывается перед чтением SV, чтобы дать ему возможность обновить своё внутреннее значение (get в $. записывает номер строки последнего прочитанного файла в слот IV SV), а set вызывается после записи в SV, чтобы дать ему возможность использовать изменённое значение (set в $/ копирует новое значение SV в глобальную переменную PL_rs).

Магия реализуется как связанный список структур MAGIC, прикреплённых к SV. Каждая структура MAGIC содержит тип магии, указатель на массив функций, которые реализуют функции get(), set(), length() и т. д., а также место для некоторых флагов и указателей. Например, связанная переменная имеет структуру MAGIC, которая содержит указатель на объект, связанный с типом.

mg_clear

Очистить что-то магическое, что представляет SV. См. "sv_magic".

int  mg_clear(SV *sv)
mg_copy

Копирует магию из одного SV в другой. См. "sv_magic".

int  mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
MGf_COPY
MGf_DUP
MGf_LOCAL

Описание в perlguts.

mg_find

Находит указатель магии для type, соответствующий SV. См. "sv_magic".

MAGIC *  mg_find(const SV *sv, int type)
mg_findext

Находит указатель магии type с заданным vtbl для SV. См. "sv_magicext".

MAGIC *  mg_findext(const SV *sv, int type, const MGVTBL *vtbl)
mg_free

Освободить любое магическое хранилище, используемое SV. См. "sv_magic".

int  mg_free(SV *sv)
mg_freeext

Удалить любую магию типа how с использованием виртуальной таблицы vtbl из SV sv. См. "sv_magic".

mg_freeext(sv, how, NULL) эквивалентно mg_free_type(sv, how).

void  mg_freeext(SV *sv, int how, const MGVTBL *vtbl)
mg_free_type

Удалить любую магию типа how из SV sv. См. "sv_magic".

void  mg_free_type(SV *sv, int how)
mg_get

Выполнить магию перед получением значения из SV. Тип SV должен быть >= SVt_PVMG. См. "sv_magic".

int  mg_get(SV *sv)
mg_magical

Включает магическое состояние SV. См. "sv_magic".

void  mg_magical(SV *sv)
mg_set

Выполнить магию после присвоения значения SV. См. "sv_magic".

int  mg_set(SV *sv)
MGVTBL

Описание в perlguts.

END_OF_DOCUMENT_MARKER
PERL_MAGIC_arylen
PERL_MAGIC_arylen_p
PERL_MAGIC_backref
PERL_MAGIC_bm
PERL_MAGIC_checkcall
PERL_MAGIC_collxfrm
PERL_MAGIC_dbfile
PERL_MAGIC_dbline
PERL_MAGIC_debugvar
PERL_MAGIC_defelem
PERL_MAGIC_destruct
PERL_MAGIC_env
PERL_MAGIC_envelem
PERL_MAGIC_ext
PERL_MAGIC_extvalue
PERL_MAGIC_fm
PERL_MAGIC_hints
PERL_MAGIC_hintselem
PERL_MAGIC_hook
PERL_MAGIC_hookelem
PERL_MAGIC_isa
PERL_MAGIC_isaelem
PERL_MAGIC_lvref
PERL_MAGIC_nkeys
PERL_MAGIC_nonelem
PERL_MAGIC_overload_table
PERL_MAGIC_pos
PERL_MAGIC_qr
PERL_MAGIC_regdata
PERL_MAGIC_regdatum
PERL_MAGIC_regex_global
PERL_MAGIC_rhash
PERL_MAGIC_shared
PERL_MAGIC_shared_scalar
PERL_MAGIC_sig
PERL_MAGIC_sigelem
PERL_MAGIC_substr
PERL_MAGIC_sv
PERL_MAGIC_symtab
PERL_MAGIC_taint
PERL_MAGIC_tied
PERL_MAGIC_tiedelem
PERL_MAGIC_tiedscalar
PERL_MAGIC_utf8
PERL_MAGIC_uvar
PERL_MAGIC_uvar_elem
PERL_MAGIC_vec
PERL_MAGIC_vstring

Описание в perlguts.

SvTIED_obj

Описание в perlinterp.

SvTIED_obj(SV *sv, MAGIC *mg)

Управление памятью

dump_mstats

При включении с помощью компиляции с -DDEBUGGING_MSTATS, выводит статистику о malloc в виде двух строк чисел: первая — длина свободного списка для каждой категории размеров, вторая — количество mallocs - frees для каждой категории размеров.

s, если не NULL, используется как фраза для включения в вывод, например, "после компиляции".

void  dump_mstats(const char *s)
HASATTRIBUTE_MALLOC

Можем ли мы обработать атрибут GCC для функций типа malloc?

HAS_MALLOC_GOOD_SIZE

Если эта символьная константа определена, это означает, что функция malloc_good_size доступна для использования.

HAS_MALLOC_SIZE

Если эта символьная константа определена, это означает, что функция malloc_size доступна для использования.

I_MALLOCMALLOC

Если эта символьная константа определена, C-программа должна включать malloc/malloc.h.

#ifdef I_MALLOCMALLOC
    #include <mallocmalloc.h>
#endif
MYMALLOC

Если эта символьная константа определена, мы используем собственную функцию malloc.

Newx
safemalloc

Интерфейс XSUB-писателя к C-функции malloc.

Выделенную память можно ТОЛЬКО освободить с помощью "Safefree".

В версии 5.9.3 Newx() и друзья заменяют более старый API New(), удаляя первый параметр, x (помощник отладки, позволявший идентифицировать вызывающих функции). Этот помощник был заменён новым параметром компиляции PERL_MEM_LOG (см. "PERL_MEM_LOG" в perlhacktips). Более старый API по-прежнему доступен для использования в XS-модулях, поддерживающих более старые версии Perl.

void   Newx      (void* ptr, int nitems, type)
void*  safemalloc(size_t size)
Newxc

Интерфейс XSUB-писателя к C-функции malloc с приведением типов. См. также "Newx".

Выделенную память можно ТОЛЬКО освободить с помощью "Safefree".

void  Newxc(void* ptr, int nitems, type, cast)
Newxz
safecalloc

Интерфейс XSUB-писателя к C-функции malloc. Выделенная память обнуляется с помощью memzero. См. также "Newx".

Выделенную память можно ТОЛЬКО освободить с помощью "Safefree".

void   Newxz     (void* ptr, int nitems, type)
void*  safecalloc(size_t nitems, size_t item_size)
PERL_MALLOC_WRAP

Если эта символьная константа определена, мы хотим проверки обертки malloc.

Renew
saferealloc

Интерфейс XSUB-писателя к C-функции realloc.

Выделенную память можно ТОЛЬКО освободить с помощью "Safefree".

void   Renew      (void* ptr, int nitems, type)
void*  saferealloc(void *ptr, size_t size)
Renewc

Интерфейс XSUB-писателя к C-функции realloc с приведением типов.

Выделенную память можно ТОЛЬКО освободить с помощью "Safefree".

void  Renewc(void* ptr, int nitems, type, cast)
Safefree

Интерфейс XSUB-писателя к C-функции free.

Используйте только для памяти, выделенной с помощью "Newx" и друзей.

void  Safefree(void* ptr)
safesyscalloc

Безопасная версия системной функции calloc()

Malloc_t  safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
safesysfree

Безопасная версия системной функции free()

Free_t  safesysfree(Malloc_t where)
safesysmalloc

Параноидальная версия системной функции malloc()

Malloc_t  safesysmalloc(MEM_SIZE nbytes)
safesysrealloc

Параноидальная версия системной функции realloc()

Malloc_t  safesysrealloc(Malloc_t where, MEM_SIZE nbytes)

MRO

Эти функции связаны с порядком разрешения методов (MRO) классов Perl. Также см. perlmroapi.

HvMROMETA

Описание в perlmroapi.

struct mro_meta *  HvMROMETA(HV *hv)
mro_get_from_name

Возвращает ранее зарегистрированный MRO с заданным name, или NULL, если не зарегистрирован. См. "mro_register".

ПРИМЕЧАНИЕ: mro_get_from_name необходимо явно вызывать как Perl_mro_get_from_name с параметром aTHX_. 

const struct mro_alg *  Perl_mro_get_from_name(pTHX_ SV *name)
mro_get_linear_isa

Возвращает линейную структуру MRO для данного хранилища. По умолчанию это то, что возвращает mro_get_linear_isa_dfs, если для хранилища не задан другой MRO. Результат — неизменяемый массив AV*, содержащий строковые значения SVs с именами классов.

Вы несете ответственность за SvREFCNT_inc() по возвращаемому значению, если планируете хранить его где-либо постоянно (иначе оно может быть удалено, в следующий раз, когда кэш будет обновлён).

AV *  mro_get_linear_isa(HV *stash)
MRO_GET_PRIVATE_DATA

Описание в perlmroapi.

SV*  MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta,
                          const struct mro_alg *const which)
mro_method_changed_in

Обнуляет кеширование методов для всех дочерних классов данного хранилища, чтобы они могли заметить изменения в нём.

В идеале, все случаи PL_sub_generation++ в исходном коде Perl, за пределами mro.c, должны быть заменены вызовами этой функции.

Perl автоматически обрабатывает большинство общих способов переопределения метода. Однако есть несколько способов изменить метод в хранилище без того, чтобы код кэша это заметил. В этом случае вам нужно вызвать этот метод позже:

1) Прямое манипулирование записями хранилища HV из XS-кода.

2) Назначение ссылки на неизменяемую скалярную константу в запись хранилища, чтобы создать постоянную подпрограмму (как это делает constant.pm).

Эта же функция доступна в чистом Perl через mro::method_changed_in(classname).

void  mro_method_changed_in(HV *stash)
mro_register

Регистрирует плагин пользовательского MRO. См. perlmroapi для получения подробной информации об этой и других функциях MRO.

ПРИМЕЧАНИЕ: mro_register необходимо явно вызывать как Perl_mro_register с параметром aTHX_.

void  Perl_mro_register(pTHX_ const struct mro_alg *mro)
mro_set_mro

Установить meta на значение, содержащееся в зарегистрированном плагине MRO с именем name.

Возвращает ошибку, если name не зарегистрирован.

ПРИМЕЧАНИЕ: mro_set_mro необходимо явно вызывать как Perl_mro_set_mro с параметром aTHX_.

void  Perl_mro_set_mro(pTHX_ struct mro_meta * const meta,
                       SV * const name)
mro_set_private_data

Описание в perlmroapi.

ПРИМЕЧАНИЕ: mro_set_private_data необходимо явно вызывать как Perl_mro_set_private_data с параметром aTHX_.

SV *  Perl_mro_set_private_data(pTHX_
                               struct mro_meta * const smeta,
                               const struct mro_alg * const which,
                               SV * const data)

Функции Multicall

dMULTICALL

Объявляет локальные переменные для multicall. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

dMULTICALL;
MULTICALL

Создаёт лёгкий обратный вызов. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

MULTICALL;
POP_MULTICALL

Закрывающая скобка для лёгкого обратного вызова. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

POP_MULTICALL;
PUSH_MULTICALL

Открывающая скобка для лёгкого обратного вызова. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

PUSH_MULTICALL(CV* the_cv);

Функции с числовыми значениями

Atol

DEPRECATED! Планируется удалить Atol из будущей версии Perl. Не используйте её в новом коде; удалите из существующего кода.

Описание в perlhacktips.

Atol(const char * nptr)
Atoul

DEPRECATED! Планируется удалить Atoul из будущей версии Perl. Не используйте его в новом коде; удалите его из существующего кода.

Описание в perlhacktips.

Atoul(const char * nptr)
Drand01

Эта макрокоманда предназначена для генерации равномерно распределённых случайных чисел в диапазоне [0., 1[. Возможно, вам потребуется указать 'extern double drand48();' в вашей программе, так как SunOS 4.1.3 не предоставляет ничего соответствующего в своих заголовках. См. "HAS_DRAND48_PROTO".

double  Drand01()
Gconvert

Эта макрокоманда препроцессора определена для преобразования числа с плавающей запятой в строку без заключительной десятичной точки. Это эмулирует поведение sprintf("%g"), но иногда намного эффективнее. Если gconvert() недоступен, но gcvt() удаляет заключительную десятичную точку, то используется gcvt(). В противном случае используется макрос с sprintf("%g"). Аргументы макрокоманды Gconvert: значение, количество цифр, нужно ли сохранять заключительные нули и буфер вывода. Обычно значения:

d_Gconvert='gconvert((x),(n),(t),(b))'
d_Gconvert='gcvt((x),(n),(b))'
d_Gconvert='sprintf((b),"%.*g",(n),(x))'

Последние два предполагают, что заключительные нули не должны сохраняться.

char *  Gconvert(double x, Size_t n, bool t, char * b)
grok_atoUV

разбирает строку, ища десятичное беззнаковое целое число.

При входе pv указывает на начало строки; valptr указывает на UV, который получит преобразованное значение, если найдено; endptr равен NULL или указывает на переменную, которая указывает на один байт за точкой в pv, которую эта процедура должна просмотреть. Если endptr равен NULL, то pv предполагается, что он имеет нуль-терминатор.

Возвращает FALSE, если pv не представляет допустимое беззнаковое целое число (без ведущих нулей). В противном случае возвращает TRUE и устанавливает *valptr в это значение.

Если вы ограничиваете часть pv, которая рассматривается этой функцией (передав ненулевой endptr), и если начальные байты этой части образуют допустимое значение, она вернёт TRUE, установив *endptr на байт, следующий за последней цифрой значения. Но если нет ограничения на рассматриваемую область, весь pv должен быть допустим для возврата TRUE. *endptr не меняется от своего значения на входе, если возвращается FALSE;

Единственные принимаемые символы — десятичные цифры '0'..'9'.

В отличие от atoi(3) или strtol(3), grok_atoUV не допускает необязательных начальных пробелов, а также отрицательных значений. Если эти функции необходимы, вызывающий код должен явно реализовать их.

Обратите внимание, что эта функция возвращает FALSE для входных данных, которые вызовут переполнение UV или содержат ведущие нули. Так, одно 0 принимается, но не 00 ни 01, 002, и т.д.

Примечание: atoi имеет серьёзные проблемы с недопустимыми входными данными, он не может использоваться для пошагового разбора и, следовательно, должен быть избегнут atoi и strtol также зависят от настроек локали, что также можно рассматривать как ошибку (глобальное состояние, контролируемое пользователем).

bool  grok_atoUV(const char *pv, UV *valptr, const char **endptr)
grok_bin

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

На входе start и *len_p задают строку для сканирования, *flags задаёт флаги преобразования, а result должно быть NULL или указателем на NV. Сканирование останавливается в конце строки или перед первым недопустимым символом. Если PERL_SCAN_SILENT_ILLDIGIT не установлено в *flags, обнаружение недопустимого символа (кроме NUL) также вызовет предупреждение. При возврате *len_p устанавливается в длину просканированной строки, а *flags даёт флаги вывода.

Если значение меньше или равно UV_MAX, оно возвращается как UV, флаги вывода сбрасываются, и ничего не записывается в *result. Если значение больше UV_MAX, grok_bin возвращает UV_MAX, устанавливает PERL_SCAN_GREATER_THAN_UV_MAX в флагах вывода и записывает приблизительное значение в *result (который является NV; или приближение отбрасывается, если result равен NULL).

Двоичное число может необязательно иметь префикс "0b" или "b", если PERL_SCAN_DISALLOW_PREFIX не установлено в *flags на входе.

Если PERL_SCAN_ALLOW_UNDERSCORES установлено в *flags, то любые или все пары цифр могут быть разделены одиночной подчёркиванием; также принимается одиночная ведущая подчёркивание.

UV  grok_bin(const char *start, STRLEN *len_p, I32 *flags,
             NV *result)
grok_hex

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

На входе start и *len_p задают строку для сканирования, *flags задаёт флаги преобразования, а result должно быть NULL или указателем на NV. Сканирование останавливается в конце строки или перед первым недопустимым символом. Если PERL_SCAN_SILENT_ILLDIGIT не установлено в *flags, обнаружение недопустимого символа (кроме NUL) также вызовет предупреждение. При возврате *len_p устанавливается в длину просканированной строки, а *flags даёт флаги вывода.

Если значение меньше или равно UV_MAX, оно возвращается как UV, флаги вывода сбрасываются, и ничего не записывается в *result. Если значение больше UV_MAX, grok_hex возвращает UV_MAX, устанавливает PERL_SCAN_GREATER_THAN_UV_MAX в флагах вывода и записывает приблизительное значение в *result (который является NV; или приближение отбрасывается, если result равен NULL).

Шестнадцатеричное число может необязательно иметь префикс "0x" или "x", если PERL_SCAN_DISALLOW_PREFIX не установлено в *flags на входе.

Если PERL_SCAN_ALLOW_UNDERSCORES установлено в *flags, то любые или все пары цифр могут быть разделены одиночной подчёркиванием; также принимается одиночная ведущая подчёркивание.

UV  grok_hex(const char *start, STRLEN *len_p, I32 *flags,
             NV *result)
grok_infnan

Вспомогательная функция для grok_number(), принимает различные способы написания «бесконечность» или «не число», и возвращает одну из следующих комбинаций флагов:

IS_NUMBER_INFINITY
IS_NUMBER_NAN
IS_NUMBER_INFINITY | IS_NUMBER_NEG
IS_NUMBER_NAN | IS_NUMBER_NEG
0

возможно, |-ed с IS_NUMBER_TRAILING.

Если распознана бесконечность или «не число», *sp укажет на байт после конца распознанной строки. Если распознавание не удалось, возвращается ноль, и *sp не сдвинется.

int  grok_infnan(const char **sp, const char *send)
grok_number

Идентично grok_number_flags() с flags установленным в ноль.

int  grok_number(const char *pv, STRLEN len, UV *valuep)
grok_number_flags

Распознаёт (или нет) число. Тип числа возвращается (0, если не распознано), в противном случае это битовая комбинация IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (определены в perl.h).

Если значение числа может поместиться в UV, оно возвращается в *valuep. IS_NUMBER_IN_UV будет установлено, чтобы указать, что *valuep является допустимым, IS_NUMBER_IN_UV никогда не будет установлено, если *valuep не является допустимым, но *valuep может быть назначено во время обработки, даже если IS_NUMBER_IN_UV не установлено при возврате. Если valuep равно NULL, IS_NUMBER_IN_UV будет установлено для тех же случаев, что и когда valuep не равно нулю, но никакого фактического назначения (или SEGV) не произойдёт.

IS_NUMBER_NOT_INT будет установлено с IS_NUMBER_IN_UV, если были обнаружены заключительные десятичные точки (в этом случае *valuep даёт истинное значение, усечённое до целого), и IS_NUMBER_NEG, если число отрицательное (в этом случае *valuep содержит абсолютное значение). IS_NUMBER_IN_UV не устанавливается, если использовалась e запись или число больше, чем UV.

flags допускает только PERL_SCAN_TRAILING, что допускает заключительный нечисловой текст в случае успешного grok, устанавливая IS_NUMBER_TRAILING в результате.

int  grok_number_flags(const char *pv, STRLEN len, UV *valuep,
                       U32 flags)
GROK_NUMERIC_RADIX

Синоним для "grok_numeric_radix"

bool  GROK_NUMERIC_RADIX(NN const char **sp, NN const char *send)
grok_numeric_radix

Сканирование и пропуск числового десятичного разделителя (разделителя).

bool  grok_numeric_radix(const char **sp, const char *send)
grok_oct

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

На входе start и *len_p задают строку для сканирования, *flags задаёт флаги преобразования, а result должно быть NULL или указателем на NV. Сканирование останавливается в конце строки или перед первым недопустимым символом. Если PERL_SCAN_SILENT_ILLDIGIT не установлено в *flags, обнаружение недопустимого символа (кроме NUL) также вызовет предупреждение. При возврате *len_p устанавливается в длину просканированной строки, а *flags даёт флаги вывода.

Если значение меньше или равно UV_MAX, оно возвращается как UV, флаги вывода сбрасываются, и ничего не записывается в *result. Если значение больше UV_MAX, grok_oct возвращает UV_MAX, устанавливает PERL_SCAN_GREATER_THAN_UV_MAX в флагах вывода и записывает приблизительное значение в *result (который является NV; или приближение отбрасывается, если result равен NULL).

Если PERL_SCAN_ALLOW_UNDERSCORES установлено в *flags, то любые или все пары цифр могут быть разделены одиночной подчёркиванием; также принимается одиночная ведущая подчёркивание.

Флаг PERL_SCAN_DISALLOW_PREFIX всегда обрабатывается как установленный для этой функции.

UV  grok_oct(const char *start, STRLEN *len_p, I32 *flags,
             NV *result)
isinfnan

Perl_isinfnan() — это вспомогательная функция, которая возвращает TRUE, если аргумент NV является бесконечностью или «не числом», FALSE в противном случае. Для более подробной проверки используйте Perl_isinf() и Perl_isnan().

Это также логическое отрицание Perl_isfinite().

bool  isinfnan(NV nv)
my_atof

atof(3), но правильно работает с обработкой локали Perl, всегда принимая точку как разделитель, но также и разделитель текущей локали, если и только если вызвана внутри лексического пространства оператора Perl use locale.

Примечание: s должен иметь нуль-терминатор.

NV  my_atof(const char *s)
my_strtod

Эта функция эквивалентна функции libc strtod(), и доступна даже на платформах, где обычная strtod() отсутствует. Её возвращаемое значение имеет наилучшую доступную точность в зависимости от возможностей платформы и опций Configure.

Она корректно обрабатывает символ разделителя десятичной дроби в соответствии с локалью, то есть ожидает точку, за исключением случаев вызова из области действия use locale, в котором случае символом разделителя должна быть точка, заданная текущей локалью.

Вместо неё можно использовать синоним Strtod().

NV  my_strtod(const char * const s, char **e)
PERL_ABS

Бестиповая abs или fabs, и т. д. (Ниже показано использование для целых чисел, но оно работает для любого типа.) Используйте вместо них, поскольку функции C-библиотеки принуждают их аргумент быть того типа, который они ожидают, что потенциально может привести к катастрофе. Но также будьте осторожны, что этот аргумент вычисляется дважды, поэтому нет x++.

int  PERL_ABS(int x)
Perl_acos
Perl_asin
Perl_atan
Perl_atan2
Perl_ceil
Perl_cos
Perl_cosh
Perl_exp
Perl_floor
Perl_fmod
Perl_frexp
Perl_isfinite
Perl_isinf
Perl_isnan
Perl_ldexp
Perl_log
Perl_log10
Perl_modf
Perl_pow
Perl_sin
Perl_sinh
Perl_sqrt
Perl_tan
Perl_tanh

Эти функции выполняют соответствующую математическую операцию над операндом(ами), используя функцию libc, предназначенную для этой задачи, которая имеет достаточную точность для NV на данной платформе. Если такой функции с достаточной точностью не существует, используется функция с наибольшей доступной точностью.

NV  Perl_acos    (NV x)
NV  Perl_asin    (NV x)
NV  Perl_atan    (NV x)
NV  Perl_atan2   (NV x, NV y)
NV  Perl_ceil    (NV x)
NV  Perl_cos     (NV x)
NV  Perl_cosh    (NV x)
NV  Perl_exp     (NV x)
NV  Perl_floor   (NV x)
NV  Perl_fmod    (NV x, NV y)
NV  Perl_frexp   (NV x, int *exp)
IV  Perl_isfinite(NV x)
IV  Perl_isinf   (NV x)
IV  Perl_isnan   (NV x)
NV  Perl_ldexp   (NV x, int exp)
NV  Perl_log     (NV x)
NV  Perl_log10   (NV x)
NV  Perl_modf    (NV x, NV *iptr)
NV  Perl_pow     (NV x, NV y)
NV  Perl_sin     (NV x)
NV  Perl_sinh    (NV x)
NV  Perl_sqrt    (NV x)
NV  Perl_tan     (NV x)
NV  Perl_tanh    (NV x)
Perl_signbit

ПРИМЕЧАНИЕ: Perl_signbit является экспериментальной и может быть изменена или удалена без предварительного уведомления.

Возвращает ненулевое целое число, если бит знака NV установлен, и 0, если он не установлен.

Если Configure обнаруживает, что данная система имеет signbit(), которая будет работать с нашими NV, тогда мы просто используем её через #define в perl.h. В противном случае используется данная реализация. Основное назначение этой функции — отлавливать -0.0.

Configure примечания: Эта функция называется 'Perl_signbit' вместо простой 'signbit', так как легко представить систему, имеющую функцию или макрос signbit(), который не работает с нашими конкретными NV. Мы не должны просто переопределять #define signbit как Perl_signbit и ожидать, что стандартные заголовки системы будут довольны. Кроме того, это функция без контекста (без pTHX_), потому что Perl_signbit() обычно переопределяется в perl.h как простой макрос вызова системной функции signbit(). Пользователи должны всегда вызывать Perl_signbit().

int  Perl_signbit(NV f)
PL_hexdigit

Этот массив, индексируемый целым числом, преобразует это значение в символ, который его представляет. Например, если входное значение равно 8, результат будет строкой, первым символом которой является '8'. На самом деле возвращается указатель в строку. Вас интересует только первый символ этой строки. Для получения прописных букв (для значений 10..15) добавьте 16 к индексу. Следовательно, PL_hexdigit[11] равно 'b', а PL_hexdigit[11+16] равно 'B'. Добавление 16 к индексу, чьё представление — '0'..'9', даёт то же самое, что и без добавления 16. Индексы вне диапазона 0..31 приводят к (плохому) неопределённому поведению.

READ_XDIGIT

Возвращает значение шестнадцатеричной цифры ASCII-диапазона и перемещает указатель строки. Поведение определено только тогда, когда isXDIGIT(*str) истинно.

U8  READ_XDIGIT(char str*)
scan_bin

Для обратной совместимости. Используйте grok_bin вместо этого.

NV  scan_bin(const char *start, STRLEN len, STRLEN *retlen)
scan_hex

Для обратной совместимости. Используйте grok_hex вместо этого.

NV  scan_hex(const char *start, STRLEN len, STRLEN *retlen)
scan_oct

Для обратной совместимости. Используйте grok_oct вместо этого.

NV  scan_oct(const char *start, STRLEN len, STRLEN *retlen)
seedDrand01

Этот символ определяет макрос, используемый для инициализации генератора случайных чисел (см. "Drand01").

void  seedDrand01(Rand_seed_t x)
Strtod

Это синоним для "my_strtod".

NV  Strtod(NN const char * const s, NULLOK char ** e)
Strtol

Независимая от платформы и конфигурации strtol. Это расширение до соответствующей функции типа strotol, основанное на платформе и опциях Configure. Например, может быть расширено до strtoll или strtoq вместо strtol.

NV  Strtol(NN const char * const s, NULLOK char ** e, int base)
Strtoul

Независимая от платформы и конфигурации strtoul. Это расширение до соответствующей функции типа strotoul, основанное на платформе и опциях Configure. Например, может быть расширено до strtoull или strtouq вместо strtoul.

NV  Strtoul(NN const char * const s, NULLOK char ** e, int base)

Optrees

alloccopstash

ПРИМЕЧАНИЕ: alloccopstash является экспериментальной и может быть изменена или удалена без предварительного уведомления.

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

PADOFFSET  alloccopstash(HV *hv)
BINOP

Описание в perlguts.

block_end

Обрабатывает выход из области видимости во время компиляции. floor — индекс стека сохранений, возвращённый block_start, а seq — тело блока. Возвращает блок, возможно, изменённый.

OP *  block_end(I32 floor, OP *seq)
block_start

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

int  block_start(int full)
ck_entersub_args_list

Выполняет стандартную обработку аргументов в дереве операций entersub. Она заключается в применении контекста списка к каждой из операций аргументов. Это стандартное обращение, используемое для вызова, помеченного как &, или для вызова метода, или для вызова через ссылку на подпрограмму, или для любого другого вызова, где вызываемая подпрограмма не может быть идентифицирована во время компиляции, или для вызова, где вызываемая подпрограмма не имеет прототипа.

OP *  ck_entersub_args_list(OP *entersubop)
ck_entersub_args_proto

Выполняет обработку аргументов в дереве операций entersub на основе прототипа подпрограммы. Это выполняет различные изменения в операциях аргументов, от применения контекста до вставки операций refgen, и проверки количества и синтаксических типов аргументов в соответствии с прототипом. Это стандартное обращение, используемое для вызова подпрограммы, не помеченной как &, где вызываемая подпрограмма может быть идентифицирована во время компиляции и имеет прототип.

protosv предоставляет прототип вызываемой подпрограммы для применения к вызову. Он может быть обычным скаляром, значение строки которого будет использоваться. Кроме того, для удобства, он может быть объектом подпрограммы (CV*, преобразованным в SV*), у которого есть прототип. Предоставляемый прототип в любом формате не обязательно должен совпадать с фактической вызываемой подпрограммой, на которую ссылается дерево операций.

Если операции аргументов не соответствуют прототипу, например, из-за недопустимого количества аргументов, всё же возвращается корректное дерево операций. Ошибка отражается в состоянии анализатора, обычно приводя к единственному исключению на верхнем уровне анализа, которое охватывает все ошибки компиляции, которые произошли. В сообщении об ошибке вызываемая подпрограмма обозначается именем, определённым параметром namegv.

OP *  ck_entersub_args_proto(OP *entersubop, GV *namegv,
                             SV *protosv)
ck_entersub_args_proto_or_list

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

protosv предоставляет прототип вызываемой подпрограммы для применения к вызову или указывает, что прототипа нет. Это может быть обычный скаляр, в этом случае, если он определён, его строковое значение будет использоваться как прототип, а если он не определён, прототип отсутствует. Кроме того, для удобства, он может быть объектом подпрограммы (CV*, преобразованным в SV*), прототип которого будет использован, если он существует. Предоставляемый прототип (или его отсутствие) в любом формате не обязательно должен совпадать с фактической вызываемой подпрограммой, на которую ссылается дерево операций.

Если операции аргументов не соответствуют прототипу, например, из-за недопустимого количества аргументов, всё же возвращается корректное дерево операций. Ошибка отражается в состоянии анализатора, обычно приводя к единственному исключению на верхнем уровне анализа, которое охватывает все ошибки компиляции, которые произошли. В сообщении об ошибке вызываемая подпрограмма обозначается именем, определённым параметром namegv.

OP *  ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
                                     SV *protosv)
cv_const_sv

Если cv является константной подпрограммой, подходящей для инлайнинга, возвращает константное значение, возвращаемое подпрограммой. В противном случае возвращает NULL.

Константные подпрограммы могут быть созданы с помощью newCONSTSUB или, как описано в "Constant Functions" в perlsub.

SV *  cv_const_sv(const CV * const cv)
cv_get_call_checker

Оригинальная форма "cv_get_call_checker_flags", которая не возвращает флаги проверяющей функции. При использовании функции проверки, возвращённой этой функцией, безопасно вызывать её только с реальным GV в качестве аргумента namegv.

void  cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
                          SV **ckobj_p)
END_OF_DOCUMENT_MARKER
cv_get_call_checker_flags

Возвращает функцию, которая будет использоваться для обработки вызова cv. Конкретно, функция применяется к дереву операций entersub для вызова подпрограммы, не помеченной &, где вызываемый объект может быть идентифицирован во время компиляции как cv.

Указатель на функцию C-уровня возвращается в *ckfun_p, аргумент SV для неё возвращается в *ckobj_p, а флаги управления возвращаются в *ckflags_p. Функция предназначена для вызова следующим образом:

entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));

В этом вызове entersubop — указатель на операцию entersub, которая может быть заменена функцией проверки, а namegv предоставляет имя, которое должна использовать функция проверки для ссылки на вызываемый объект операции entersub, если ей требуется вывести какие-либо диагностические сообщения. Разрешено применять функцию проверки в нестандартных ситуациях, таких как вызов другой подпрограммы или вызов метода.

namegv фактически может не быть GV. Если бит *ckfun_p в *ckflags_p сброшен, разрешено передать CV или другой SV вместо него, всё, что может быть использовано в качестве первого аргумента для "cv_name". Если бит CALL_CHECKER_REQUIRE_GV установлен в *ckflags_p, то функция проверки требует, чтобы namegv был истинным GV.

По умолчанию, функцией проверки является Perl_ck_entersub_args_proto_or_list, параметр SV — это само cv , а флаг CALL_CHECKER_REQUIRE_GV сброшен. Это реализует стандартную обработку прототипов. Можно изменить её для конкретной подпрограммы с помощью "cv_set_call_checker_flags".

Если бит CALL_CHECKER_REQUIRE_GV установлен в gflags, это означает, что вызывающий код знает только о версии namegv типа GV, и соответственно соответствующий бит всегда будет установлен в *ckflags_p, независимо от требований, записанных в функции проверки. Если бит CALL_CHECKER_REQUIRE_GV сброшен в gflags, это означает, что вызывающий код знает о возможности передачи чего-либо, кроме GV, в качестве namegv, и соответственно соответствующий бит может быть установлен или сброшен в *ckflags_p, что указывает на требования функции проверки.

gflags — это набор битов, передаваемый в cv_get_call_checker_flags, в котором только бит CALL_CHECKER_REQUIRE_GV в настоящее время имеет определённый смысл (см. выше). Все остальные биты должны быть сброшены.

void  cv_get_call_checker_flags(CV *cv, U32 gflags,
                                Perl_call_checker *ckfun_p,
                                SV **ckobj_p, U32 *ckflags_p)
cv_set_call_checker

Исходная форма "cv_set_call_checker_flags", которая передаёт флаг CALL_CHECKER_REQUIRE_GV для обратной совместимости. Влияние установки этого флага заключается в том, что функция проверки гарантированно получит настоящий GV в качестве аргумента namegv. 

void  cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
                          SV *ckobj)
cv_set_call_checker_flags

Устанавливает функцию, которая будет использоваться для обработки вызова cv. Конкретно, функция применяется к дереву операций entersub для вызова подпрограммы, не помеченной &, где вызываемый объект может быть идентифицирован во время компиляции как cv.

Указатель на функцию C-уровня предоставляется в ckfun, аргумент SV для неё предоставляется в ckobj, а флаги управления предоставляются в ckflags. Функция должна быть определена следующим образом:

STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)

Она предназначена для вызова следующим образом:

entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);

В этом вызове entersubop — указатель на операцию entersub, которая может быть заменена функцией проверки, а namegv предоставляет имя, которое должна использовать функция проверки для ссылки на вызываемый объект операции entersub, если ей требуется вывести какие-либо диагностические сообщения. Разрешено применять функцию проверки в нестандартных ситуациях, таких как вызов другой подпрограммы или вызов метода.

namegv может фактически не быть GV. Для повышения эффективности Perl может передать вместо него CV или другой SV. Передаваемое значение может быть использовано в качестве первого аргумента для "cv_name". Вы можете принудительно заставить Perl передать GV, включив CALL_CHECKER_REQUIRE_GV в ckflags.

ckflags — это набор битов, в котором только бит CALL_CHECKER_REQUIRE_GV в настоящее время имеет определённый смысл (см. выше). Все остальные биты должны быть сброшены.

Текущие настройки для конкретного CV можно получить с помощью "cv_get_call_checker_flags".

void  cv_set_call_checker_flags(CV *cv, Perl_call_checker ckfun,
                                SV *ckobj, U32 ckflags)
finalize_optree

Эта функция завершает обработку дерева операций. Необходимо вызывать её сразу после построения полного дерева операций. Она выполняет дополнительные проверки, которые невозможно сделать в обычных функциях ck_xxx, и делает дерево потокобезопасным.

void  finalize_optree(OP *o)
forbid_outofblock_ops

ПРИМЕЧАНИЕ: forbid_outofblock_ops — экспериментальная функция и может быть изменена или удалена без предварительного уведомления.

Проверяет дерево операций, реализующее блок, чтобы убедиться, что нет операций потока управления, пытающихся покинуть блок. Любые OP_RETURN запрещены, как и любые OP_GOTO. Циклы анализируются, поэтому разрешены операции LOOPEX (OP_NEXT, OP_LAST или OP_REDO) влияющие на цикл, содержащий их внутри блока, но запрещены те, которые не делают этого.

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

Эта функция сама по себе не достаточна для гарантии, что дерево операций не выполняет ни одну из этих запрещённых операций во время выполнения, так как она может вызвать другую функцию, выполняющую нелокальный LOOPEX, или string-eval(), выполняющую goto, или различные другие действия. Она предназначена исключительно для проверки на этапе компиляции тех, которые могут быть обнаружены статически. В зависимости от ситуации, для которой она используется, могут потребоваться дополнительные проверки во время выполнения.

Обратите внимание, что в настоящее время все операции OP_GOTO запрещены, даже в тех случаях, когда они могут быть безопасны для выполнения. Возможно, это будет разрешено в будущих версиях.

void  forbid_outofblock_ops(OP *o, const char *blockname)
LINKLIST

Учитывая корень дерева операций, связывает дерево в порядке выполнения с помощью указателей op_next и возвращает первую выполняемую операцию. Если это уже было выполнено, оно не будет переделано, и будет возвращено значение o->op_next. Если o->op_next ещё не задано, o должен быть как минимум UNOP.

OP*  LINKLIST(OP *o)
LISTOP

Описание в perlguts.

LOGOP

Описание в perlguts.

LOOP

Описание в perlguts.

newARGDEFELEMOP

Создаёт и возвращает новую операцию OP_ARGDEFELEM, которая предоставляет выражение по умолчанию, заданное expr для параметра подписи по индексу, указанному argindex . Дерево выражения, потребляется этой функцией и становится частью возвращаемого дерева операций.

OP *  newARGDEFELEMOP(I32 flags, OP *expr, I32 argindex)
newASSIGNOP

Создаёт, проверяет и возвращает операцию присваивания. left и right предоставляют параметры присваивания; они потребляются этой функцией и становятся частью построенного дерева операций.

Если optype равно OP_ANDASSIGN, OP_ORASSIGN или OP_DORASSIGN, тогда строится соответствующее условное дерево операций. Если optype является кодом операции бинарной операции, такой как OP_BIT_OR, то строится операция, которая выполняет бинарную операцию и присваивает результат левому аргументу. В любом случае, если optype отлично от нуля, то flags не имеет эффекта.

Если optype равно нулю, то строится простое присваивание скаляра или списка. Тип присваивания определяется автоматически. flags даёт восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь бит, восемь битов op_private, за исключением того, что бит со значением 1 или 2 автоматически устанавливается, как требуется.

OP *  newASSIGNOP(I32 flags, OP *left, I32 optype, OP *right)
newATTRSUB

Создаёт подпрограмму Perl, выполняя также некоторые дополнительные задачи.

Это то же самое, что и "newATTRSUB_x" в perlintern, за исключением того, что параметр o_is_gv установлен в FALSE. Это означает, что если o равно null, новая подпрограмма будет анонимной; в противном случае имя будет получено из o так, как описано (как и все другие детали) в "newATTRSUB_x" в perlintern.

CV *  newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs,
                 OP *block)
newBINOP

Создаёт, проверяет и возвращает операцию любого бинарного типа. type — это код операции. flags даёт восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь бит, восемь битов op_private, за исключением того, что бит со значением 1 или 2 автоматически устанавливается, как требуется. first и last предоставляют до двух операций, которые должны стать прямыми потомками бинарной операции; они потребляются этой функцией и становятся частью построенного дерева операций.

OP *  newBINOP(I32 type, I32 flags, OP *first, OP *last)
newCONDOP

Создаёт, проверяет и возвращает условную (cond_expr) операцию. flags даёт восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь бит, восемь битов op_private, за исключением того, что бит со значением 1 автоматически устанавливается. first предоставляет выражение, выбирающее между двумя ветвями, а trueop и falseop предоставляют ветви; они потребляются этой функцией и становятся частью построенного дерева операций.

OP *  newCONDOP(I32 flags, OP *first, OP *trueop, OP *falseop)
newCONSTSUB

Ведёт себя как "newCONSTSUB_flags", за исключением того, что name имеет нуль-терминатор, а не заданную длину, и не устанавливаются никакие флаги. (Это означает, что name всегда интерпретируется как Latin-1.)

CV *  newCONSTSUB(HV *stash, const char *name, SV *sv)
newCONSTSUB_flags

Создайте константную подпрограмму, также выполняя некоторые окружающие задачи. Скалярная подпрограмма с константным значением подходит для инлайнинга во время компиляции, и в коде Perl её можно создать с помощью sub FOO () { 123 }. Другие типы константных подпрограмм обрабатываются по-другому.

У подпрограммы будет пустой прототип, и она будет игнорировать любые аргументы при вызове. Её константное поведение определяется sv. Если sv равно null, подпрограмма вернёт пустой список. Если sv указывает на скаляр, подпрограмма всегда вернёт этот скаляр. Если sv указывает на массив, подпрограмма всегда вернёт список элементов этого массива в контексте списка или количество элементов в массиве в скалярном контексте. Эта функция принимает во владение один учтённый ссылку на скаляр или массив и позаботится о том, чтобы объект прожил столько же, сколько и подпрограмма. Если sv указывает на скаляр, то инлайнинг предполагает, что значение скаляра никогда не изменится, поэтому вызывающая сторона должна гарантировать, что скаляр впоследствии не будет изменён. Если sv указывает на массив, то такое предположение не делается, поэтому в теории безопасно изменять массив или его элементы, но подтверждено ли это на практике, не определено.

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

Если name равно null, то подпрограмма будет анонимной, при этом её CvGV будет ссылаться на __ANON__ глобальную переменную. Если name не равно null, то подпрограмма будет иметь имя соответственно, ссылаться на соответствующую глобальную переменную. name — это строка длиной len байт, задающая имя символа без модификаторов, в UTF-8, если flags имеет бит SVf_UTF8, и в Latin-1 в противном случае. Имя может быть квалифицированным или неквалифицированным. Если имя неквалифицированное, оно по умолчанию находится в стеке, указанном stash, если оно не равно null, или в стеке PL_curstash, если stash равно null. Символ всегда добавляется в стек при необходимости, с семантикой GV_ADDMULTI.

flags не должно иметь установленных битов, кроме SVf_UTF8.

Если уже существует подпрограмма с указанным именем, новая подпрограмма заменит существующую в глобальной переменной. Может быть сгенерировано предупреждение о повторном определении.

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

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

CV *  newCONSTSUB_flags(HV *stash, const char *name, STRLEN len,
                        U32 flags, SV *sv)
newDEFEROP

ПРИМЕЧАНИЕ: newDEFEROP является экспериментальным и может быть изменено или удалено без предварительного уведомления.

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

Аргумент flags несёт дополнительные флаги для установки на возвращённый оператор, включая поле op_private.

OP *  newDEFEROP(I32 flags, OP *block)
newDEFSVOP

Создаёт и возвращает оператор для доступа к $_.

OP *  newDEFSVOP()
newFOROP

Создаёт, проверяет и возвращает дерево операций, выражающее цикл foreach (итерацию по списку значений). Это цикл тяжёлого типа, с структурой, позволяющей выйти из цикла с помощью last и подобных конструкций.

sv необязательно предоставляет переменную(ые), которая(ые) будут алиасированы к каждому элементу по очереди; если null, по умолчанию используется $_. expr предоставляет список значений, по которым следует итерироваться. block предоставляет основной блок цикла, и cont необязательно предоставляет блок continue, который работает как вторая половина тела. Все эти входные данные дерева операций потребляются этой функцией и становятся частью созданного дерева операций.

flags задаёт восемь бит op_flags для оператора leaveloop и, сдвинутые влево на восемь бит, восемь бит op_private для оператора leaveloop, за исключением того, что (в обоих случаях) некоторые биты будут установлены автоматически.

OP *  newFOROP(I32 flags, OP *sv, OP *expr, OP *block, OP *cont)
newGIVENOP

Создаёт, проверяет и возвращает дерево операций, выражающее блок given. cond предоставляет выражение, значение которого $_ будет локально алиасировано, а block предоставляет тело конструкции given; они потребляются этой функцией и становятся частью созданного дерева операций. defsv_off должно быть нулём (использовалось для идентификации слота стека лексической $_).

OP *  newGIVENOP(OP *cond, OP *block, PADOFFSET defsv_off)
newGVOP

Создаёт, проверяет и возвращает оператор любого типа, который включает встроенную ссылку на GV. type — код операции. flags задаёт восемь бит op_flags. gv идентифицирует GV, на который должен ссылаться оператор; вызов этой функции не передаёт владения ссылкой на него.

OP *  newGVOP(I32 type, I32 flags, GV *gv)
newLISTOP

Создаёт, проверяет и возвращает оператор любого типа списка. type — код операции. flags задаёт восемь бит op_flags, за исключением того, что OPf_KIDS будет установлено автоматически при необходимости. first и last предоставляют до двух операторов, которые будут прямыми дочерними элементами оператора списка; они потребляются этой функцией и становятся частью созданного дерева операций.

Для большинства операторов списка функция проверки ожидает, что все операторы-потомки уже присутствуют, поэтому вызов newLISTOP(OP_JOIN, ...) (например) не подходит. В этом случае нужно создать оператор типа OP_LIST, добавить к нему дополнительные потомки и затем вызвать "op_convert_list". Подробнее об этом см. "op_convert_list".

OP *  newLISTOP(I32 type, I32 flags, OP *first, OP *last)
newLOGOP

Создаёт, проверяет и возвращает логический (управляющий потоком) оператор. type — код операции. flags задаёт восемь бит op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутые влево на восемь бит, восемь бит op_private, за исключением того, что бит со значением 1 будет автоматически установлен. first предоставляет выражение, управляющее потоком, а other предоставляет побочную (альтернативную) цепочку операторов; они потребляются этой функцией и становятся частью созданного дерева операций.

OP *  newLOGOP(I32 optype, I32 flags, OP *first, OP *other)
newLOOPEX

Создаёт, проверяет и возвращает оператор выхода из цикла (например, goto или last). type — код операции. label предоставляет параметр, определяющий целевой оператор; он потребляется этой функцией и становится частью созданного дерева операций.

OP *  newLOOPEX(I32 type, OP *label)
newLOOPOP

Создаёт, проверяет и возвращает дерево операций, выражающее цикл. Это только цикл в потоке управления через дерево операций; он не имеет структуры цикла тяжёлого типа, которая позволяет выйти из цикла с помощью last и подобных конструкций. flags задаёт восемь бит op_flags для оператора верхнего уровня, за исключением того, что некоторые биты будут установлены автоматически по необходимости. expr предоставляет выражение, управляющее итерацией цикла, а block предоставляет тело цикла; они потребляются этой функцией и становятся частью созданного дерева операций. debuggable в настоящее время не используется и всегда должно быть равно 1.

OP *  newLOOPOP(I32 flags, I32 debuggable, OP *expr, OP *block)
newMETHOP

Создаёт, проверяет и возвращает оператор типа метода с именем метода, оцениваемым во время выполнения. type — код операции. flags задаёт восемь бит op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутые влево на восемь бит, восемь бит op_private, за исключением того, что бит со значением 1 будет автоматически установлен. dynamic_meth предоставляет оператор, который оценивает имя метода; он потребляется этой функцией и становится частью созданного дерева операций. Поддерживаемые типы операторов: OP_METHOD.

OP *  newMETHOP(I32 type, I32 flags, OP *dynamic_meth)
newMETHOP_named

Создаёт, проверяет и возвращает оператор типа метода с постоянным именем метода. type — код операции. flags задаёт восемь бит op_flags, и, сдвинутые влево на восемь бит, восемь бит op_private. const_meth предоставляет постоянное имя метода; оно должно быть общей строкой COW. Поддерживаемые типы операторов: OP_METHOD_NAMED.

OP *  newMETHOP_named(I32 type, I32 flags, SV * const_meth)
newNULLLIST

Создаёт, проверяет и возвращает новый оператор stub, который представляет пустое выражение списка.

OP *  newNULLLIST()
newOP

Создаёт, проверяет и возвращает оператор любого базового типа (любой тип без дополнительных полей). type — код операции. flags задаёт восемь бит op_flags, и, сдвинутые влево на восемь бит, восемь бит op_private.

OP *  newOP(I32 optype, I32 flags)
newPADOP

Создаёт, проверяет и возвращает оператор любого типа, включающий ссылку на элемент блока. type — код операции. flags предоставляет восемь бит op_flags. Слот блока автоматически выделяется и заполняется sv; данная функция принимает во владение одну ссылку на него.

Эта функция существует только если Perl был скомпилирован с использованием ithreads.

OP *  newPADOP(I32 type, I32 flags, SV *sv)
newPMOP

Создаёт, проверяет и возвращает оператор любого типа сопоставления с образцом. type — код операции. flags предоставляет восемь бит op_flags и, сдвинутые влево на восемь бит, восемь бит op_private.

OP *  newPMOP(I32 type, I32 flags)
newPVOP

Создаёт, проверяет и возвращает оператор любого типа, включающий встроенный C-уровневый указатель (PV). type — код операции. flags предоставляет восемь бит op_flags. pv предоставляет C-уровневый указатель. В зависимости от типа оператора, память, на которую ссылается op_flags, может быть освобождена при уничтожении оператора. Если оператор является оператором освобождения, pv должен был быть выделен с помощью PerlMemShared_malloc.

OP *  newPVOP(I32 type, I32 flags, char *pv)
newRANGE

Создаёт и возвращает оператор range, с подчиненными операторами flip и flop . flags предоставляет восемь бит op_flags для оператора flip и, сдвинутые влево на восемь бит, восемь бит op_private для операторов flip и range, за исключением того, что бит со значением 1 автоматически устанавливается. left и right предоставляют выражения, контролирующие границы диапазона; они потребляются этой функцией и становятся частью созданного дерева операторов.

OP *  newRANGE(I32 flags, OP *left, OP *right)
newSLICEOP

Создаёт, проверяет и возвращает оператор lslice (срез списка). flags предоставляет восемь бит op_flags, за исключением того, что OPf_KIDS будет автоматически установлен, и, сдвинутые влево на восемь бит, восемь бит op_private, за исключением того, что бит со значением 1 или 2 будет автоматически установлен по необходимости. listval и subscript предоставляют параметры среза; они потребляются этой функцией и становятся частью созданного дерева операторов.

OP *  newSLICEOP(I32 flags, OP *subscript, OP *listop)
newSTATEOP

Создаёт оператор состояния (COP). Оператор состояния обычно является оператором nextstate, но будет оператором dbstate, если отладка включена для текущего кода. Оператор состояния заполняется из PL_curcop (или PL_compiling). Если label не равен нулю, он предоставляет имя метки для присоединения к оператору состояния; эта функция принимает во владение память, на которую указывает label, и освободит её. flags предоставляет восемь бит op_flags для оператора состояния.

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

OP *  newSTATEOP(I32 flags, char *label, OP *o)
newSUB

Подобно "newATTRSUB", но без атрибутов.

CV *  newSUB(I32 floor, OP *o, OP *proto, OP *block)
newSVOP

Создаёт, проверяет и возвращает оператор любого типа, включающий встроенный SV. type — код операции. flags предоставляет восемь бит op_flags. sv предоставляет SV для встраивания в оператор; эта функция принимает во владение одну ссылку на него.

OP *  newSVOP(I32 type, I32 flags, SV *sv)
newTRYCATCHOP

ПРИМЕЧАНИЕ: newTRYCATCHOP является экспериментальным и может быть изменён или удалён без уведомления.

Создаёт и возвращает оператор условного выполнения, который реализует семантику try/catch. Сначала выполняется дерево операторов в tryblock, внутри контекста, ловящего исключения. Если возникает исключение, выполняется дерево операторов в catchblock, при этом пойманное исключение устанавливается в лексическую переменную, заданную catchvar (которая должна быть оператором типа OP_PADSV). Все деревья операторов потребляются этой функцией и становятся частью возвращаемого дерева операторов.

Аргумент flags в настоящее время игнорируется.

OP *  newTRYCATCHOP(I32 flags, OP *tryblock, OP *catchvar,
                    OP *catchblock)
newUNOP

Создаёт, проверяет и возвращает оператор любого унарного типа. type — код операции. flags предоставляет восемь бит op_flags, за исключением того, что OPf_KIDS будет автоматически установлен, если необходимо, и, сдвинутые влево на восемь бит, восемь бит op_private, за исключением того, что бит со значением 1 автоматически устанавливается. first предоставляет необязательный оператор, который будет прямым потомком унарного оператора; он потребляется этой функцией и становится частью созданного дерева операторов.

OP *  newUNOP(I32 type, I32 flags, OP *first)
newUNOP_AUX

Аналогично newUNOP, но создаёт структуру UNOP_AUX, с op_aux инициализированным значением aux

OP *  newUNOP_AUX(I32 type, I32 flags, OP *first,
                  UNOP_AUX_item *aux)
newWHENOP

Создаёт, проверяет и возвращает дерево операторов, представляющее блок when. cond предоставляет выражение проверки, а block предоставляет блок, который будет выполнен, если выражение проверки примет значение true; они потребляются этой функцией и становятся частью созданного дерева операторов. cond будет интерпретироваться DWIM-опосредованно, часто как сравнение с $_, и может быть равно null, для генерации блока default. 

OP *  newWHENOP(OP *cond, OP *block)
newWHILEOP

Создаёт, проверяет и возвращает дерево операторов, представляющее цикл while. Это ресурсоёмкий цикл, со структурой, позволяющей выйти из цикла с помощью last и т.п.

loop — необязательный предварительно созданный оператор enterloop для использования в цикле; если он равен нулю, будет создан соответствующий оператор. expr предоставляет управляющее выражение цикла. block предоставляет основное тело цикла, а cont необязательно предоставляет блок continue, который действует как вторая половина тела. Все эти входные деревья операторов потребляются этой функцией и становятся частью созданного дерева операторов.

flags предоставляет восемь бит op_flags для оператора leaveloop и, сдвинутые влево на восемь бит, восемь бит op_private для оператора leaveloop, за исключением того, что (в обоих случаях) некоторые биты будут установлены автоматически. debuggable в настоящее время не используется и всегда должен быть равен 1. has_my может быть предоставлен как true, чтобы принудительно поместить тело цикла в свой собственный блок.

OP *  newWHILEOP(I32 flags, I32 debuggable, LOOP *loop, OP *expr,
                 OP *block, OP *cont, I32 has_my)
newXS

Используется xsubpp для подключения XSUB как подпрограмм Perl. filename должен быть статическим хранилищем, поскольку он используется напрямую как CvFILE(), без создания копии.

OA_BASEOP
OA_BINOP
OA_COP
OA_LISTOP
OA_LOGOP
OA_LOOP
OA_PADOP
OA_PMOP
OA_PVOP_OR_SVOP
OA_SVOP
OA_UNOP

Описано в perlguts.

OP

Описано в perlguts.

op_append_elem

Добавляет элемент в список операторов, содержащихся непосредственно в операторе типа список, возвращая удлинённый список. first — оператор типа список, а last — оператор для добавления в список. optype указывает предполагаемый код операции для списка. Если first ещё не является списком нужного типа, он будет преобразован в него. Если first или last равны null, возвращается другой оператор без изменений.

OP *  op_append_elem(I32 optype, OP *first, OP *last)
op_append_list

Конкатенирует списки операторов, содержащихся непосредственно в двух операторах типа список, возвращая объединённый список. first и last — операторы типа список для конкатенации. optype указывает предполагаемый код операции для списка. Если first или last ещё не являются списками нужного типа, они будут преобразованы в них. Если first или last равны null, возвращается другой оператор без изменений.

OP *  op_append_list(I32 optype, OP *first, OP *last)
OP_CLASS

Возвращает класс предоставленного оператора: то есть, какой из структур *OP он использует. Для основных операторов это в настоящее время получает информацию из PL_opargs, что не всегда точно отражает используемый тип; в версиях 5.26 и выше, см. также функцию "op_class", которая может лучше определить используемый тип.

Для пользовательских операторов тип возвращается из регистрации, и регистрируемый обязан убедиться, что он точный. Возвращаемое значение будет одним из констант OA_* из op.h.

U32  OP_CLASS(OP *o)
op_contextualize

Применяет синтаксический контекст к дереву операторов, представляющему выражение. o — дерево операторов, а context должен быть G_SCALAR, G_LIST, или G_VOID, чтобы указать контекст для применения. Возвращается изменённое дерево операторов.

OP *  op_contextualize(OP *o, I32 context)
op_convert_list

Преобразует o в оператор списка, если это не оператор списка, а затем преобразует его в указанный type, вызывая его функцию проверки, выделяя целевой объект, если он нужен, и сворачивая константы.

Оператор типа список обычно создаётся по одному потомку за раз с помощью newLISTOP, op_prepend_elem и op_append_elem. Затем, наконец, он передаётся в op_convert_list для приведения его к нужному типу.

OP *  op_convert_list(I32 optype, I32 flags, OP *o)
OP_DESC

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

const char *  OP_DESC(OP *o)
op_force_list

Преобразует o и любых его соседей в OP_LIST, если это не оператор списка. Если был создан новый оператор OP_LIST, его первый потомок будет OP_PUSHMARK. Сам возвращаемый узел будет сброшен до null, оставив только его потомков.

Это часто то, что вы хотите сделать перед тем, как поместить дерево операторов в контекст списка; как

o = op_contextualize(op_force_list(o), G_LIST);
OP *  op_force_list(OP *o)
op_free

Освободить операцию и её потомков. Используйте только тогда, когда операция больше не связана ни с одним элементом optree.

Помните, что любая операция, у которой установлен флаг OPf_KIDS, должна иметь корректный указатель op_first. Если вы пытаетесь освободить операцию, но сохранить её дочерние операции, убедитесь, что вы сбросите этот флаг перед вызовом op_free(). Например:

OP *kid = o->op_first; o->op_first = NULL;
o->op_flags &= ~OPf_KIDS;
op_free(o);
void  op_free(OP *arg)
OpHAS_SIBLING

Возвращает true, если o имеет брата или сестру.

bool  OpHAS_SIBLING(OP *o)
OpLASTSIB_set

Помечает o как не имеющий дополнительных братьев или сестер и отмечает o как имеющего указанный родитель. См. также "OpMORESIB_set" и OpMAYBESIB_set. Для интерфейса более высокого уровня см. "op_sibling_splice".

void  OpLASTSIB_set(OP *o, OP *parent)
op_linklist

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

OP *  op_linklist(OP *o)
op_lvalue

ПРИМЕЧАНИЕ: op_lvalue является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Распространяет контекст lvalue ("модифицируемый") на операцию и её потомков. type представляет тип контекста, примерно основанный на типе операции, которая бы производила модификацию, хотя local() представлен OP_NULL, поскольку у него нет собственного типа операции (он сигнализируется флагом в lvalue-операции).

Эта функция обнаруживает элементы, которые не могут быть изменены, например $x+1, и генерирует ошибки для них. Например, $x+1 = 2 приведет к вызову её с операцией типа OP_ADD и аргументом type значения OP_SASSIGN.

Она также помечает элементы, которые должны вести себя особым образом в контексте lvalue, например $$x = 5, которые могут потребовать оживления ссылки в $x.

OP *  op_lvalue(OP *o, I32 type)
OpMAYBESIB_set

Условно выполняет OpMORESIB_set или OpLASTSIB_set в зависимости от того, является ли sib ненулевым. Для интерфейса более высокого уровня см. "op_sibling_splice".

void  OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
OpMORESIB_set

Устанавливает брата или сестру o в ненулевое значение sib. См. также "OpLASTSIB_set" и "OpMAYBESIB_set". Для интерфейса более высокого уровня см. "op_sibling_splice".

void  OpMORESIB_set(OP *o, OP *sib)
OP_NAME

Возвращает имя предоставленной операции. Для основных операций это имя ищется в типе операции; для настраиваемых операций - в op_ppaddr.

const char *  OP_NAME(OP *o)
op_null

Деактивирует операцию, когда она больше не нужна, но всё ещё связана с другими операциями.

void  op_null(OP *o)
op_parent

Возвращает родительскую операцию o, если у неё есть родитель. В противном случае возвращает NULL.

OP *  op_parent(OP *o)
op_prepend_elem

Добавляет элемент в начало списка операций, содержащихся непосредственно внутри операции типа список, возвращая расширенный список. first - операция, которую нужно добавить в начало списка, и last - операция типа список. optype определяет предполагаемый код операции для списка. Если last ещё не является списком нужного типа, он будет преобразован в него. Если first или last имеют значение null, то другой возвращается без изменений.

OP *  op_prepend_elem(I32 optype, OP *first, OP *last)
op_scope

ПРИМЕЧАНИЕ: op_scope является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Обертывает дерево операций дополнительными операциями, чтобы во время выполнения создавалась динамическая область видимости. Исходные операции выполняются в новой динамической области видимости, а затем, при нормальном завершении, область видимости разворачивается. Дополнительные операции, используемые для создания и разворачивания динамической области видимости, обычно представляют собой пару enter/leave, но вместо этого может использоваться операция scope, если операции достаточно просты, чтобы не требовали полной структуры динамической области видимости.

OP *  op_scope(OP *o)
OpSIBLING

Возвращает брата или сестру o, или NULL если брата или сестры нет.

OP*  OpSIBLING(OP *o)
op_sibling_splice

Общая функция для редактирования структуры существующей цепочки узлов op_sibling. Аналогично функции splice() на уровне Perl, позволяет удалить ноль или более последовательных узлов, заменив их нулём или более другими узлами. Выполняет необходимые действия op_first/op_last для родительского узла и манипуляции op_sibling для дочерних узлов. Последний удалённый узел будет помечен как последний узел, обновляя поле op_sibling/op_sibparent или op_moresib, соответственно.

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

parent - родительский узел цепочки братьев и сестер. Его можно передать как NULL, если вставка не затрагивает первую или последнюю операцию в цепочке.

start - узел, предшествующий первому узлу, который должен быть вставлен. Узел(ы) после него будут удалены, и операции будут вставлены после него. Если это NULL, то удаляются первые узлы, а узлы вставляются в начало.

del_count - количество узлов для удаления. Если ноль, то узлы не удаляются. Если -1 или больше, чем или равно числу оставшихся детей, то удаляются все оставшиеся дети.

insert - первый из цепочки узлов, которые должны быть вставлены вместо удалённых узлов. Если NULL, узлы не вставляются.

Возвращается начало цепочки удалённых операций или NULL, если операции не были удалены.

Например:

action                    before      after         returns
------                    -----       -----         -------

                          P           P
splice(P, A, 2, X-Y-Z)    |           |             B-C
                          A-B-C-D     A-X-Y-Z-D

                          P           P
splice(P, NULL, 1, X-Y)   |           |             A
                          A-B-C-D     X-Y-B-C-D

                          P           P
splice(P, NULL, 3, NULL)  |           |             A-B-C
                          A-B-C-D     D

                          P           P
splice(P, B, 0, X-Y)      |           |             NULL
                          A-B-C-D     A-B-X-Y-C-D

Для более низкоуровневой прямой манипуляции с op_sibparent и op_moresib, см. "OpMORESIB_set", "OpLASTSIB_set", "OpMAYBESIB_set".

OP *  op_sibling_splice(OP *parent, OP *start, int del_count,
                        OP *insert)
optimize_optree

Эта функция применяет некоторые оптимизации к дереву optree сверху вниз. Она вызывается перед оптимизатором peephole, который обрабатывает операции в порядке выполнения. Обратите внимание, что finalize_optree() также выполняет сканирование сверху вниз, но вызывается *после* оптимизатора peephole.

void  optimize_optree(OP *o)
OP_TYPE_IS

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

Отрицание этого макроса, OP_TYPE_ISNT, также доступно, а также OP_TYPE_IS_NN и OP_TYPE_ISNT_NN, которые исключают проверку на нулевой указатель.

bool  OP_TYPE_IS(OP *o, Optype type)
OP_TYPE_IS_OR_WAS

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

Отрицание этого макроса, OP_TYPE_ISNT_AND_WASNT, также доступно, а также OP_TYPE_IS_OR_WAS_NN и OP_TYPE_ISNT_AND_WASNT_NN, которые исключают проверку на нулевой указатель NULL. 

bool  OP_TYPE_IS_OR_WAS(OP *o, Optype type)
op_wrap_finally

ПРИМЕЧАНИЕ: op_wrap_finally является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Обертывает фрагмент optree block в свой собственный блок области видимости, организуя вызов фрагмента optree finally при выходе из этого блока по любой причине. Оба фрагмента optree потребляются, и результат объединяется, и возвращается.

OP *  op_wrap_finally(OP *block, OP *finally)
peep_t

Описание в perlguts.

Perl_cpeep_t

Описание в perlguts.

PL_opfreehook

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

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

В многопоточных Perl'ях, каждая нить имеет независимую копию этой переменной; каждая инициализируется при создании текущим значением копии создающей нити.

Perl_ophook_t  PL_opfreehook
PL_peepp

Указатель на оптимизатор peephole для каждой подпрограммы. Это функция, которая вызывается в конце компиляции подпрограммы Perl (или, эквивалентно, независимого фрагмента кода Perl), чтобы выполнить исправления некоторых операций и выполнить оптимизации небольшого масштаба. Функция вызывается один раз для каждой компилируемой подпрограммы и получает в качестве единственного параметра указатель на операцию, являющуюся точкой входа в подпрограмму. Она изменяет дерево операций непосредственно.

Оптимизатор peephole никогда не должен полностью заменяться. Вместо этого, добавьте код в него, обернув существующий оптимизатор. Основной способ сделать это показан в "Compile pass 3: peephole optimization" в perlguts. Если новый код хочет работать с операциями на всей структуре подпрограммы, а не только на верхнем уровне, то, скорее всего, удобнее обернуть обработчик "PL_rpeepp".

В многопоточных Perl'ях, каждая нить имеет независимую копию этой переменной; каждая инициализируется при создании текущим значением копии создающей нити.

peep_t  PL_peepp
PL_rpeepp

Указатель на рекурсивный оптимизатор peephole. Это функция, которая вызывается в конце компиляции подпрограммы Perl (или, эквивалентно, независимого фрагмента кода Perl), чтобы выполнить исправления некоторых операций и выполнить оптимизации небольшого масштаба. Функция вызывается один раз для каждой цепочки операций, связанных через их поля op_next; она рекурсивно вызывается для обработки каждой боковой цепочки. Ей передаётся в качестве единственного параметра указатель на операцию, находящуюся в начале цепочки. Она изменяет дерево операций непосредственно.

Оптимизатор peephole никогда не должен полностью заменяться. Вместо этого, добавьте код в него, обернув существующий оптимизатор. Основной способ сделать это показан в "Compile pass 3: peephole optimization" в perlguts. Если новый код хочет работать только с операциями на верхнем уровне подпрограммы, а не по всей структуре, то, скорее всего, удобнее обернуть обработчик "PL_peepp".

В многопоточных Perl'ях, каждая нить имеет независимую копию этой переменной; каждая инициализируется при создании текущим значением копии создающей нити.

peep_t  PL_rpeepp
PMOP

Описание в perlguts.

END_OF_DOCUMENT_MARKER
rv2cv_op_cv

Рассматривает операцию, которая должна определить подпрограмму во время выполнения, и пытается определить во время компиляции, какую подпрограмму она идентифицирует. Это обычно используется во время компиляции Perl для определения, можно ли применить шаблон к вызову функции. cvop — это рассматриваемая операция, обычно операция rv2cv. Указатель на идентифицированную подпрограмму возвращается, если её можно было определить статически, и возвращается нулевой указатель, если это не удалось.

В настоящее время подпрограмму можно определить статически, если RV, на котором должна работать rv2cv, предоставляется подходящей операцией gv или const. Операция gv подходит, если слот CV в GV заполнен. Операция const подходит, если постоянное значение должно быть RV, указывающим на CV. Подробности этого процесса могут измениться в будущих версиях Perl. Если у операции rv2cv установлен флаг OPpENTERSUB_AMPER, попытка определить подпрограмму статически не предпринимается: этот флаг используется для подавления магических действий во время компиляции при вызове подпрограммы, заставляя её использовать стандартное поведение во время выполнения.

Если у flags установлен бит RV2CVOPCV_MARK_EARLY, то обработка ссылки на GV изменяется. Если GV был проанализирован и обнаружено, что его слот CV пуст, то у операции gv установлен флаг OPpEARLY_CV. Если операция не оптимизирована, а слот CV позже заполняется подпрограммой с шаблоном, этот флаг в конечном итоге сгенерирует предупреждение «вызов произошёл слишком рано для проверки шаблона».

Если у flags установлен бит RV2CVOPCV_RETURN_NAME_GV, вместо указателя на подпрограмму возвращается указатель на GV, дающий наиболее подходящее имя для подпрограммы в этом контексте. Обычно это просто CvGV подпрограммы, но для анонимной (CvANON) подпрограммы, на которую ссылаются через GV, это будет ссылающийся GV. Результирующий GV* приводится к типу CV*, чтобы его вернуть. Нулевой указатель возвращается как обычно, если статически определяемая подпрограмма отсутствует.

CV *  rv2cv_op_cv(OP *cvop, U32 flags)
UNOP

Описание в perlguts.

XOP

Описание в perlguts.

Упаковщик и распаковщик

packlist

Движок, реализующий функцию Perl pack(). 

void  packlist(SV *cat, const char *pat, const char *patend,
               SV **beglist, SV **endlist)
unpackstring

Движок, реализующий функцию Perl unpack().

Используя шаблон pat..patend, эта функция распаковывает строку s..strend в ряд смертных SVs, которые она помещает на стек аргументов Perl (@_) (поэтому вам потребуется выполнить PUTBACK перед и SPAGAIN после вызова этой функции). Она возвращает количество помещённых элементов.

Указатели strend и patend должны указывать на байт, следующий за последним символом каждой строки.

Хотя эта функция возвращает свои значения в стеке аргументов Perl, она не принимает параметры из этого стека (и, следовательно, особенно нет необходимости выполнять PUSHMARK перед её вызовом, в отличие от "call_pv", например).

SSize_t  unpackstring(const char *pat, const char *patend,
                      const char *s, const char *strend,
                      U32 flags)

Структуры данных падов

CvPADLIST

ПРИМЕЧАНИЕ: CvPADLIST является экспериментальным и может быть изменён или удалён без уведомления.

CV может иметь CvPADLIST(cv), установленным для указания на PADLIST. Это рабочая область CV, которая хранит лексические переменные и временные значения кода операторов и значения для каждой нити.

Для этих целей «форматы» — это разновидность CV; eval"" тоже (за исключением того, что их нельзя вызывать по желанию и они всегда удаляются после завершения выполнения eval""). Требуемые файлы — это просто evals без внешнего лексического пространства имён.

XSUB не имеют CvPADLIST. dXSTARG извлекает значения из PL_curpad, но это на самом деле рабочая область вызывающего (слот которой выделяется каждым entersub). Не получайте и не устанавливайте CvPADLIST, если CV — это XSUB (как определяется CvISXSUB()), слот CvPADLIST используется для другой внутренней цели в XSUB.

PADLIST имеет массив C, где хранятся пады.

0-й элемент PADLIST — это PADNAMELIST, представляющий «имена», или скорее «статическую информацию о типе» для лексических переменных. Индивидуальные элементы PADNAMELIST — это PADNAME.

Элемент CvDEPTH'th PADLIST — это PAD (AV), который является стековой рамкой на данной глубине рекурсии в CV. 0-й слот AV фрейма — это AV, который представляет собой @_. Другие элементы — это хранилища для переменных и целей операторов.

Итерация по PADNAMELIST итерируется по всем возможным элементам падов. Слот падов для целей (SVs_PADTMP) и GV оказываются с именами &PL_padname_undef, а слоты для констант имеют имена &PL_padname_const (см. "pad_alloc"). То, что &PL_padname_undef и &PL_padname_const используются, является деталью реализации, которая может быть изменена. Для проверки используйте !PadnamePV(name) и PadnamePV(name) && !PadnameLEN(name) соответственно.

Только переменные со слотами my/our получают действительные имена. Остальные — цели операторов/GV/константы, которые статически выделяются или разрешаются во время компиляции. У них нет имён, по которым они могут быть найдены из кода Perl во время выполнения через eval"", так как переменные my/our могут быть найдены.

Имена падов в PADNAMELIST содержат в своём PV имя переменной. Поля COP_SEQ_RANGE_LOW и _HIGH образуют диапазон (low+1..high включительно) номеров cop_seq, для которых имя является допустимым. Во время компиляции эти поля могут содержать специальное значение PERL_PADSEQ_INTRO для обозначения различных этапов:

COP_SEQ_RANGE_LOW        _HIGH
-----------------        -----
PERL_PADSEQ_INTRO            0   variable not yet introduced:
                                 { my ($x
valid-seq#   PERL_PADSEQ_INTRO   variable in scope:
                                 { my ($x);
valid-seq#          valid-seq#   compilation of scope complete:
                                 { my ($x); .... }

Когда лексическая переменная ещё не объявлена, она уже существует с точки зрения дублирования объявлений, но не для поиска переменных, например.

my ($x, $x); # '"my" variable $x masks earlier declaration'
my $x = $x;  # equal to my $x = $::x;

Для типизированных лексических переменных PadnameTYPE указывает на хранилище типа. Для our лексических переменных, PadnameOURSTASH указывает на хранилище связанного глобального объекта (чтобы можно было обнаружить дублирующие our объявления в одном пакете). PadnameGEN иногда используется для хранения номера поколения во время компиляции.

Если для имени пада установлено PadnameOUTER, то соответствующий элемент в массиве AV является ссылкой REFCNT'ed на лексическую переменную из «вне». Такие записи иногда называют «поддельными». В этом случае имя не использует «low» и «high» для хранения диапазона cop_seq, поскольку оно находится в области видимости на всём протяжении. Вместо этого «high» хранит некоторые флаги, содержащие информацию о реальной лексической переменной (объявлена ли она в анонимном блоке и может ли быть экземпляризована несколько раз?), а для поддельных анонимных блоков «low» содержит индекс в рабочем пространстве родителя, где хранится значение лексической переменной, чтобы ускорить клонирование.

Если имя «name» равно &, соответствующий элемент в PAD представляет собой CV, представляющий возможный замыкание.

Обратите внимание, что форматы обрабатываются как анонимные подпрограммы и клонируются каждый раз, когда вызывается write (при необходимости).

Флаг SVs_PADSTALE сбрасывается для лексических переменных каждый раз, когда выполняется my(), и устанавливается при выходе из области видимости. Это позволяет генерировать предупреждение "Variable $x is not available" в eval, например

{ my $x = 1; sub f { eval '$x'} } f();

Для переменных состояния SVs_PADSTALE перегружено, чтобы означать «ещё не инициализировано», но это внутреннее состояние хранится в отдельном элементе пада.

PADLIST *  CvPADLIST(CV *cv)
pad_add_name_pvs

Точно так же, как "pad_add_name_pvn", но принимает литеральную строку вместо пары строка/длина.

PADOFFSET  pad_add_name_pvs("name", U32 flags, HV *typestash,
                            HV *ourstash)
PadARRAY

ПРИМЕЧАНИЕ: PadARRAY является экспериментальным и может быть изменён или удалён без уведомления.

Массив C элементов падов.

SV **  PadARRAY(PAD * pad)
pad_findmy_pvs

Точно так же, как "pad_findmy_pvn", но принимает литеральную строку вместо пары строка/длина.

PADOFFSET  pad_findmy_pvs("name", U32 flags)
PadlistARRAY

ПРИМЕЧАНИЕ: PadlistARRAY является экспериментальным и может быть изменён или удалён без уведомления.

Массив C списка падов, содержащий пады. Подставляйте только числа >= 1, так как 0-й элемент не гарантированно останется пригодным для использования.

PAD **  PadlistARRAY(PADLIST * padlist)
PadlistMAX

ПРИМЕЧАНИЕ: PadlistMAX является экспериментальным и может быть изменён или удалён без уведомления.

Индекс последнего выделенного места в списке падов. Обратите внимание, что последний пад может находиться в более раннем слоте. Все элементы после него будут NULL в этом случае.

SSize_t  PadlistMAX(PADLIST * padlist)
PadlistNAMES

ПРИМЕЧАНИЕ: PadlistNAMES является экспериментальным и может быть изменён или удалён без уведомления.

Имена, связанные с элементами падов.

PADNAMELIST *  PadlistNAMES(PADLIST * padlist)
PadlistNAMESARRAY

ПРИМЕЧАНИЕ: PadlistNAMESARRAY является экспериментальным и может быть изменён или удалён без уведомления.

Массив C имён падов.

PADNAME **  PadlistNAMESARRAY(PADLIST * padlist)
PadlistNAMESMAX

ПРИМЕЧАНИЕ: PadlistNAMESMAX является экспериментальным и может быть изменён или удалён без уведомления.

Индекс последнего имени пада.

SSize_t  PadlistNAMESMAX(PADLIST * padlist)
PadlistREFCNT

ПРИМЕЧАНИЕ: PadlistREFCNT является экспериментальным и может быть изменён или удалён без уведомления.

Счётчик ссылок списка падов. В настоящее время он всегда равен 1.

U32  PadlistREFCNT(PADLIST * padlist)
PadMAX

ПРИМЕЧАНИЕ: PadMAX является экспериментальным и может быть изменён или удалён без уведомления.

Индекс последнего элемента пада.

SSize_t  PadMAX(PAD * pad)
PadnameLEN

ПРИМЕЧАНИЕ: PadnameLEN является экспериментальным и может быть изменён или удалён без уведомления.

Длина имени.

STRLEN  PadnameLEN(PADNAME * pn)
PadnamelistARRAY

ПРИМЕЧАНИЕ: PadnamelistARRAY является экспериментальным и может быть изменён или удалён без уведомления.

Массив C имён падов.

PADNAME **  PadnamelistARRAY(PADNAMELIST * pnl)
PadnamelistMAX

ПРИМЕЧАНИЕ: PadnamelistMAX является экспериментальным и может быть изменён или удалён без уведомления.

Индекс последнего имени пада.

SSize_t  PadnamelistMAX(PADNAMELIST * pnl)
PadnamelistREFCNT

ПРИМЕЧАНИЕ: PadnamelistREFCNT является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Счётчик ссылок списка имён подушек.

SSize_t  PadnamelistREFCNT(PADNAMELIST * pnl)
PadnamelistREFCNT_dec

ПРИМЕЧАНИЕ: PadnamelistREFCNT_dec является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Уменьшает счётчик ссылок списка имён подушек.

void  PadnamelistREFCNT_dec(PADNAMELIST * pnl)
PadnamePV

ПРИМЕЧАНИЕ: PadnamePV является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Имя, хранящееся в структуре имени подушки. Возвращает NULL для целевого слота.

char *  PadnamePV(PADNAME * pn)
PadnameREFCNT

ПРИМЕЧАНИЕ: PadnameREFCNT является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Счётчик ссылок имени подушки.

SSize_t  PadnameREFCNT(PADNAME * pn)
PadnameREFCNT_dec

ПРИМЕЧАНИЕ: PadnameREFCNT_dec является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Уменьшает счётчик ссылок имени подушки.

void  PadnameREFCNT_dec(PADNAME * pn)
PadnameREFCNT_inc

ПРИМЕЧАНИЕ: PadnameREFCNT_inc является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Увеличивает счётчик ссылок имени подушки. Возвращает само имя подушки.

PADNAME *  PadnameREFCNT_inc(PADNAME * pn)
PadnameSV

ПРИМЕЧАНИЕ: PadnameSV является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Возвращает имя подушки как смертное SV.

SV *  PadnameSV(PADNAME * pn)
PadnameUTF8

ПРИМЕЧАНИЕ: PadnameUTF8 является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Является ли PadnamePV в кодировке UTF-8. В настоящее время это всегда истинно.

bool  PadnameUTF8(PADNAME * pn)
pad_new

Создаёт новый список подушек, обновляя глобальные переменные, чтобы они указывали на новый список подушек. Следующие флаги можно объединять с помощью операции OR:

padnew_CLONE	this pad is for a cloned CV
padnew_SAVE		save old globals on the save stack
padnew_SAVESUB	also save extra stuff for start of sub
PADLIST *  pad_new(int flags)
PL_comppad

ПРИМЕЧАНИЕ: PL_comppad является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Во время компиляции указывает на массив, содержащий часть значений подушки для текущего компилируемого кода. (Во время выполнения CV может иметь много таких массивов значений; во время компиляции создаётся только один.) Во время выполнения указывает на массив, содержащий текущие соответствующие значения для подушки для текущего выполняемого кода.

PL_comppad_name

ПРИМЕЧАНИЕ: PL_comppad_name является экспериментальным и может быть изменён или удалён без предварительного уведомления.

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

PL_curpad

ПРИМЕЧАНИЕ: PL_curpad является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Указывает непосредственно на тело массива "PL_comppad". (То есть, это PadARRAY(PL_comppad).)

SVs_PADMY

DEPRECATED! Планируется удалить SVs_PADMY из будущей версии Perl. Не используйте его в новом коде; удалите его из существующего кода.

Описано в perlguts.

SVs_PADTMP

Описано в perlguts.

Доступ к паролям и группам

GRPASSWD

Если этот символ определён, то C-программа понимает, что struct group в grp.h содержит gr_passwd.

HAS_ENDGRENT

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

HAS_ENDGRENT_R

Если этот символ определён, это указывает, что процедура endgrent_r доступна для завершения getgrent в режиме повторного входа.

HAS_ENDPWENT

Если этот символ определён, это указывает, что процедура endpwent доступна для завершения последовательного доступа к базе данных паролей.

HAS_ENDPWENT_R

Если этот символ определён, это указывает, что процедура endpwent_r доступна для завершения endpwent в режиме повторного входа.

HAS_GETGRENT

Если этот символ определён, это указывает, что процедура getgrent доступна для последовательного доступа к базе данных групп.

HAS_GETGRENT_R

Если этот символ определён, это указывает, что процедура getgrent_r доступна для getgrent в режиме повторного входа.

HAS_GETPWENT

Если этот символ определён, это указывает, что процедура getpwent доступна для последовательного доступа к базе данных паролей. Если это недоступно, может быть доступна более старая функция getpw().

HAS_GETPWENT_R

Если этот символ определён, это указывает, что процедура getpwent_r доступна для getpwent в режиме повторного входа.

HAS_SETGRENT

Если этот символ определён, это указывает, что процедура setgrent доступна для инициализации последовательного доступа к базе данных групп.

HAS_SETGRENT_R

Если этот символ определён, это указывает, что процедура setgrent_r доступна для setgrent в режиме повторного входа.

HAS_SETPWENT

Если этот символ определён, это указывает, что процедура setpwent доступна для инициализации последовательного доступа к базе данных паролей.

HAS_SETPWENT_R

Если этот символ определён, это указывает, что процедура setpwent_r доступна для setpwent в режиме повторного входа.

PWAGE

Если этот символ определён, то C-программа понимает, что struct passwd содержит pw_age.

PWCHANGE

Если этот символ определён, то C-программа понимает, что struct passwd содержит pw_change.

PWCLASS

Если этот символ определён, то C-программа понимает, что struct passwd содержит pw_class.

PWCOMMENT

Если этот символ определён, то C-программа понимает, что struct passwd содержит pw_comment.

PWEXPIRE

Если этот символ определён, то C-программа понимает, что struct passwd содержит pw_expire.

PWGECOS

Если этот символ определён, то C-программа понимает, что struct passwd содержит pw_gecos.

PWPASSWD

Если этот символ определён, то C-программа понимает, что struct passwd содержит pw_passwd.

PWQUOTA

Если этот символ определён, то C-программа понимает, что struct passwd содержит pw_quota.

Пути к системным командам

CSH

Если этот символ определён, он содержит полный путь к csh.

LOC_SED

Этот символ содержит полный путь к программе sed.

SH_PATH

Этот символ содержит полный путь к оболочке, используемой в этой системе для выполнения скриптов оболочки Bourne. Обычно это будет /bin/sh, хотя возможно, что на некоторых системах это будет /bin/ksh, /bin/pdksh, /bin/ash, /bin/bash или даже что-то вроде D:/bin/sh.exe.

Информация о прототипах

CRYPT_R_PROTO

Этот символ кодирует прототип crypt_r. Он равен нулю, если d_crypt_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_crypt_r определён.

CTERMID_R_PROTO

Этот символ кодирует прототип ctermid_r. Он равен нулю, если d_ctermid_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_ctermid_r определён.

DRAND48_R_PROTO

Этот символ кодирует прототип drand48_r. Он равен нулю, если d_drand48_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_drand48_r определён.

ENDGRENT_R_PROTO

Этот символ кодирует прототип endgrent_r. Он равен нулю, если d_endgrent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_endgrent_r определён.

ENDHOSTENT_R_PROTO

Этот символ кодирует прототип endhostent_r. Он равен нулю, если d_endhostent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_endhostent_r определён.

ENDNETENT_R_PROTO

Этот символ кодирует прототип endnetent_r. Он равен нулю, если d_endnetent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_endnetent_r определён.

ENDPROTOENT_R_PROTO

Этот символ кодирует прототип endprotoent_r. Он равен нулю, если d_endprotoent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_endprotoent_r определён.

ENDPWENT_R_PROTO

Этот символ кодирует прототип endpwent_r. Он равен нулю, если d_endpwent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_endpwent_r определён.

ENDSERVENT_R_PROTO

Этот символ кодирует прототип endservent_r. Он равен нулю, если d_endservent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_endservent_r определён.

GDBMNDBM_H_USES_PROTOTYPES

Если этот символ определён, это указывает, что gdbm/ndbm.h использует реальные ANSI C-прототипы вместо прототипов в стиле K&R без информации о параметрах. Хотя ANSI C-прототипы поддерживаются в C++, прототипы в стиле K&R приведут к ошибкам.

GDBM_NDBM_H_USES_PROTOTYPES

Этот символ, если определён, указывает, что <gdbm-ndbm.h> использует реальные ANSI C прототипы вместо деклараций функций в стиле K&R без какой-либо информации о параметрах. Хотя ANSI C прототипы поддерживаются в C++, декларации функций в стиле K&R приведут к ошибкам.

GETGRENT_R_PROTO

Этот символ кодирует прототип getgrent_r. Он равен нулю, если d_getgrent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getgrent_r определён.

GETGRGID_R_PROTO

Этот символ кодирует прототип getgrgid_r. Он равен нулю, если d_getgrgid_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getgrgid_r определён.

GETGRNAM_R_PROTO

Этот символ кодирует прототип getgrnam_r. Он равен нулю, если d_getgrnam_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getgrnam_r определён.

GETHOSTBYADDR_R_PROTO

Этот символ кодирует прототип gethostbyaddr_r. Он равен нулю, если d_gethostbyaddr_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_gethostbyaddr_r определён.

GETHOSTBYNAME_R_PROTO

Этот символ кодирует прототип gethostbyname_r. Он равен нулю, если d_gethostbyname_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_gethostbyname_r определён.

GETHOSTENT_R_PROTO

Этот символ кодирует прототип gethostent_r. Он равен нулю, если d_gethostent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_gethostent_r определён.

GETLOGIN_R_PROTO

Этот символ кодирует прототип getlogin_r. Он равен нулю, если d_getlogin_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getlogin_r определён.

GETNETBYADDR_R_PROTO

Этот символ кодирует прототип getnetbyaddr_r. Он равен нулю, если d_getnetbyaddr_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getnetbyaddr_r определён.

GETNETBYNAME_R_PROTO

Этот символ кодирует прототип getnetbyname_r. Он равен нулю, если d_getnetbyname_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getnetbyname_r определён.

GETNETENT_R_PROTO

Этот символ кодирует прототип getnetent_r. Он равен нулю, если d_getnetent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getnetent_r определён.

GETPROTOBYNAME_R_PROTO

Этот символ кодирует прототип getprotobyname_r. Он равен нулю, если d_getprotobyname_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getprotobyname_r определён.

GETPROTOBYNUMBER_R_PROTO

Этот символ кодирует прототип getprotobynumber_r. Он равен нулю, если d_getprotobynumber_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getprotobynumber_r определён.

GETPROTOENT_R_PROTO

Этот символ кодирует прототип getprotoent_r. Он равен нулю, если d_getprotoent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getprotoent_r определён.

GETPWENT_R_PROTO

Этот символ кодирует прототип getpwent_r. Он равен нулю, если d_getpwent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getpwent_r определён.

GETPWNAM_R_PROTO

Этот символ кодирует прототип getpwnam_r. Он равен нулю, если d_getpwnam_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getpwnam_r определён.

GETPWUID_R_PROTO

Этот символ кодирует прототип getpwuid_r. Он равен нулю, если d_getpwuid_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getpwuid_r определён.

GETSERVBYNAME_R_PROTO

Этот символ кодирует прототип getservbyname_r. Он равен нулю, если d_getservbyname_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getservbyname_r определён.

GETSERVBYPORT_R_PROTO

Этот символ кодирует прототип getservbyport_r. Он равен нулю, если d_getservbyport_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getservbyport_r определён.

GETSERVENT_R_PROTO

Этот символ кодирует прототип getservent_r. Он равен нулю, если d_getservent_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getservent_r определён.

GETSPNAM_R_PROTO

Этот символ кодирует прототип getspnam_r. Он равен нулю, если d_getspnam_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_getspnam_r определён.

HAS_DBMINIT_PROTO

Этот символ, если определён, указывает, что система предоставляет прототип для функции dbminit(). В противном случае, прототип должен предоставить программа. Хорошая оценка —

extern int dbminit(char *);
HAS_DRAND48_PROTO

Этот символ, если определён, указывает, что система предоставляет прототип для функции drand48(). В противном случае, прототип должен предоставить программа. Хорошая оценка —

extern double drand48(void);
HAS_FLOCK_PROTO

Этот символ, если определён, указывает, что система предоставляет прототип для функции flock(). В противном случае, прототип должен предоставить программа. Хорошая оценка —

extern int flock(int, int);
HAS_GETHOST_PROTOS

Этот символ, если определён, указывает, что netdb.h включает прототипы для gethostent(), gethostbyname(), и gethostbyaddr(). В противном случае, их должна определить программа. Для поиска различных типов Netdb_xxx_t см. netdbtype.U (часть metaconfig).

HAS_GETNET_PROTOS

Этот символ, если определён, указывает, что netdb.h включает прототипы для getnetent(), getnetbyname(), и getnetbyaddr(). В противном случае, их должна определить программа. Для поиска различных типов Netdb_xxx_t см. netdbtype.U (часть metaconfig).

HAS_GETPROTO_PROTOS

Этот символ, если определён, указывает, что netdb.h включает прототипы для getprotoent(), getprotobyname(), и getprotobyaddr(). В противном случае, их должна определить программа. Для поиска различных типов Netdb_xxx_t см. netdbtype.U (часть metaconfig).

HAS_GETSERV_PROTOS

Этот символ, если определён, указывает, что netdb.h включает прототипы для getservent(), getservbyname(), и getservbyaddr(). В противном случае, их должна определить программа. Для поиска различных типов Netdb_xxx_t см. netdbtype.U (часть metaconfig).

HAS_MODFL_PROTO

Этот символ, если определён, указывает, что система предоставляет прототип для функции modfl(). В противном случае, прототип должен предоставить программа.

HAS_SBRK_PROTO

Этот символ, если определён, указывает, что система предоставляет прототип для функции sbrk(). В противном случае, прототип должен предоставить программа. Хорошие оценки —

extern void* sbrk(int);
extern void* sbrk(size_t);
HAS_SETRESGID_PROTO

Этот символ, если определён, указывает, что система предоставляет прототип для функции setresgid(). В противном случае, прототип должен предоставить программа. Хорошие оценки —

extern int setresgid(uid_t ruid, uid_t euid, uid_t suid);
HAS_SETRESUID_PROTO

Этот символ, если определён, указывает, что система предоставляет прототип для функции setresuid(). В противном случае, прототип должен предоставить программа. Хорошие оценки —

extern int setresuid(uid_t ruid, uid_t euid, uid_t suid);
HAS_SHMAT_PROTOTYPE

Этот символ, если определён, указывает, что sys/shm.h содержит прототип для shmat(). В противном случае, прототип должен указать программа. Shmat_t shmat(int, Shmat_t, int) — хорошая оценка, но не всегда верна, поэтому она должна генерироваться программой только тогда, когда HAS_SHMAT_PROTOTYPE не определён, чтобы избежать конфликтов определений.

HAS_SOCKATMARK_PROTO

Этот символ, если определён, указывает, что система предоставляет прототип для функции sockatmark(). В противном случае, прототип должен предоставить программа. Хорошая оценка —

extern int sockatmark(int);
HAS_SYSCALL_PROTO

Этот символ, если определён, указывает, что система предоставляет прототип для функции syscall(). В противном случае, прототип должен предоставить программа. Хорошие оценки —

extern int syscall(int,  ...);
extern int syscall(long, ...);
HAS_TELLDIR_PROTO

Этот символ, если определён, указывает, что система предоставляет прототип для функции telldir(). В противном случае, прототип должен предоставить программа. Хорошая оценка —

extern long telldir(DIR*);
NDBM_H_USES_PROTOTYPES

Этот символ, если определён, указывает, что ndbm.h использует реальные ANSI C прототипы вместо деклараций функций в стиле K&R без какой-либо информации о параметрах. Хотя ANSI C прототипы поддерживаются в C++, декларации функций в стиле K&R приведут к ошибкам.

RANDOM_R_PROTO

Этот символ кодирует прототип random_r. Он равен нулю, если d_random_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_random_r определён.

READDIR_R_PROTO

Этот символ кодирует прототип readdir_r. Он равен нулю, если d_readdir_r не определён, и одному из REENTRANT_PROTO_T_ABC макросов из reentr.h, если d_readdir_r определён.

END_OF_DOCUMENT_MARKER
SETGRENT_R_PROTO

Этот символ кодирует прототип setgrent_r. Он равен нулю, если d_setgrent_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_setgrent_r определён.

SETHOSTENT_R_PROTO

Этот символ кодирует прототип sethostent_r. Он равен нулю, если d_sethostent_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_sethostent_r определён.

SETLOCALE_R_PROTO

Этот символ кодирует прототип setlocale_r. Он равен нулю, если d_setlocale_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_setlocale_r определён.

SETNETENT_R_PROTO

Этот символ кодирует прототип setnetent_r. Он равен нулю, если d_setnetent_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_setnetent_r определён.

SETPROTOENT_R_PROTO

Этот символ кодирует прототип setprotoent_r. Он равен нулю, если d_setprotoent_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_setprotoent_r определён.

SETPWENT_R_PROTO

Этот символ кодирует прототип setpwent_r. Он равен нулю, если d_setpwent_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_setpwent_r определён.

SETSERVENT_R_PROTO

Этот символ кодирует прототип setservent_r. Он равен нулю, если d_setservent_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_setservent_r определён.

SRANDOM_R_PROTO

Этот символ кодирует прототип srandom_r. Он равен нулю, если d_srandom_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_srandom_r определён.

SRAND48_R_PROTO

Этот символ кодирует прототип srand48_r. Он равен нулю, если d_srand48_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_srand48_r определён.

STRERROR_R_PROTO

Этот символ кодирует прототип strerror_r. Он равен нулю, если d_strerror_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_strerror_r определён.

TMPNAM_R_PROTO

Этот символ кодирует прототип tmpnam_r. Он равен нулю, если d_tmpnam_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_tmpnam_r определён.

TTYNAME_R_PROTO

Этот символ кодирует прототип ttyname_r. Он равен нулю, если d_ttyname_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из файла reentr.h, если d_ttyname_r определён.

Функции REGEXP

pregcomp

Описание в perlreguts.

REGEXP *  pregcomp(SV * const pattern, const U32 flags)
pregexec

Описание в perlreguts.

I32  pregexec(REGEXP * const prog, char *stringarg, char *strend,
              char *strbeg, SSize_t minend, SV *screamer,
              U32 nosave)
re_compile

Компилирует шаблон регулярного выражения pattern, возвращая указатель на скомпилированный объект для последующего сопоставления с внутренним движком регулярных выражений.

Эта функция обычно используется пользовательским движком регулярных выражений .comp() для передачи тех шаблонов, которые он не хочет обрабатывать самостоятельно (обычно передавая те же флаги, с которыми он был вызван). Практически во всех остальных случаях регулярное выражение должно быть скомпилировано вызовом "pregcomp" для компиляции с использованием текущего активного движка регулярных выражений.

Если pattern уже является REGEXP, эта функция ничего не делает, кроме возвращения указателя на вход. В противном случае PV извлекается и обрабатывается как строка, представляющая шаблон. См. perlre.

Возможные флаги для rx_flags описаны в perlreapi. Их имена все начинаются с RXf_.

REGEXP *  re_compile(SV * const pattern, U32 orig_rx_flags)
re_dup_guts

Дублирование регулярного выражения.

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

После дублирования всех данных ядра, хранящихся в структуре regexp, используется метод regexp_engine.dupe для копирования любых частных данных, хранящихся в указателе *pprivate. Это позволяет расширениям обрабатывать любые необходимые дублирования.

void  re_dup_guts(const REGEXP *sstr, REGEXP *dstr,
                  CLONE_PARAMS *param)
REGEX_LOCALE_CHARSET

Описание в perlreapi.

REGEXP

Описание в perlreapi.

regexp_engine

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

Для установки нового обработчика регулярных выражений $^H{regcomp} устанавливается на целое число, которое (при соответствующем приведении типа) ссылается на одну из этих структур. При компиляции выполняется метод comp, а ожидается, что поле engine полученной структуры regexp указывает обратно на ту же структуру.

Символ pTHX_ в определении — макрос, используемый Perl в многопоточном режиме, чтобы предоставить дополнительный аргумент процедуре, содержащей указатель на интерпретатор, выполняющий регулярное выражение. Поэтому во всех многопоточных процедурах есть дополнительный аргумент.

regexp_paren_pair

Описание в perlreapi.

regmatch_info

Некоторая базовая информация о текущем совпадении, созданная Perl_regexec_flags и затем переданная в regtry(), regmatch() и т. д. Она выделяется как локальная переменная на стеке, поэтому в ней ничего не должно храниться, что нужно сохранить или очистить при вызове croak(). Для этого см. члены aux_info и aux_info_eval объединения regmatch_state.

REXEC_COPY_SKIP_POST
REXEC_COPY_SKIP_PRE
REXEC_COPY_STR

Описание в perlreapi.

RXapif_ALL
RXapif_CLEAR
RXapif_DELETE
RXapif_EXISTS
RXapif_FETCH
RXapif_FIRSTKEY
RXapif_NEXTKEY
RXapif_ONE
RXapif_REGNAME
RXapif_REGNAMES
RXapif_REGNAMES_COUNT
RXapif_SCALAR
RXapif_STORE

Описание в perlreapi.

RX_BUFF_IDX_CARET_FULLMATCH
RX_BUFF_IDX_CARET_POSTMATCH
RX_BUFF_IDX_CARET_PREMATCH
RX_BUFF_IDX_FULLMATCH
RX_BUFF_IDX_POSTMATCH
RX_BUFF_IDX_PREMATCH

Описание в perlreapi.

RXf_NO_INPLACE_SUBST
RXf_NULL
RXf_SKIPWHITE
RXf_SPLIT
RXf_START_ONLY
RXf_WHITE

Описание в perlreapi.

RXf_PMf_EXTENDED
RXf_PMf_FOLD
RXf_PMf_KEEPCOPY
RXf_PMf_MULTILINE
RXf_PMf_SINGLELINE

Описание в perlreapi.

RX_MATCH_COPIED

Описание в perlreapi.

RX_MATCH_COPIED(const REGEXP * rx)
RX_OFFS

Описание в perlreapi.

RX_OFFS(const REGEXP * rx_sv)
SvRX

Удобный макрос для получения REGEXP из SV. Это примерно эквивалентно следующему фрагменту:

if (SvMAGICAL(sv))
    mg_get(sv);
if (SvROK(sv))
    sv = MUTABLE_SV(SvRV(sv));
if (SvTYPE(sv) == SVt_REGEXP)
    return (REGEXP*) sv;

NULL будет возвращено, если REGEXP* не найден.

REGEXP *  SvRX(SV *sv)
SvRXOK

Возвращает булево значение, указывающее, является ли SV (или SV, на который он ссылается) REGEXP.

Если вы хотите сделать что-то с REGEXP* позже, используйте SvRX и проверьте на NULL.

bool  SvRXOK(SV* sv)
SV_SAVED_COPY

Описание в perlreapi.

Отчёты и Форматы

Используются в простом инструменте генерации отчётов Perl. См. perlform.

IoBOTTOM_GV

Описание в perlguts.

GV *  IoBOTTOM_GV(IO *io)
IoBOTTOM_NAME

Описание в perlguts.

char *  IoBOTTOM_NAME(IO *io)
IoFMT_GV

Описание в perlguts.

GV *  IoFMT_GV(IO *io)
IoFMT_NAME

Описание в perlguts.

char *  IoFMT_NAME(IO *io)
IoLINES

Описание в perlguts.

IV  IoLINES(IO *io)
IoLINES_LEFT

Описание в perlguts.

IV  IoLINES_LEFT(IO *io)
IoPAGE

Описание в perlguts.

IV  IoPAGE(IO *io)
IoPAGE_LEN

Описание в perlguts.

IV  IoPAGE_LEN(IO *io)
IoTOP_GV

Описание в perlguts.

GV *  IoTOP_GV(IO *io)
IoTOP_NAME

Описание в perlguts.

char *  IoTOP_NAME(IO *io)

Сигналы

HAS_SIGINFO_SI_ADDR

Если этот символ определён, это означает, что siginfo_t имеет член si_addr

END_OF_DOCUMENT_MARKER
HAS_SIGINFO_SI_BAND

Этот символ, если определён, указывает, что siginfo_t содержит член si_band

HAS_SIGINFO_SI_ERRNO

Этот символ, если определён, указывает, что siginfo_t содержит член si_errno

HAS_SIGINFO_SI_PID

Этот символ, если определён, указывает, что siginfo_t содержит член si_pid

HAS_SIGINFO_SI_STATUS

Этот символ, если определён, указывает, что siginfo_t содержит член si_status

HAS_SIGINFO_SI_UID

Этот символ, если определён, указывает, что siginfo_t содержит член si_uid

HAS_SIGINFO_SI_VALUE

Этот символ, если определён, указывает, что siginfo_t содержит член si_value

PERL_SIGNALS_UNSAFE_FLAG

Если этот бит в PL_signals установлен, система использует небезопасные сигналы, предшествующие Perl 5.8. См. "PERL_SIGNALS" в perlrun и "Отложенные сигналы (Безопасные сигналы)" в perlipc.

U32  PERL_SIGNALS_UNSAFE_FLAG
rsignal

Обёртка для функций C-библиотеки sigaction(2) или signal(2). Используйте её вместо этих функций libc, так как Perl-версия предоставляет наиболее безопасную реализацию и знает о взаимодействии с остальной частью интерпретатора Perl.

Sighandler_t  rsignal(int i, Sighandler_t t)
rsignal_state

Возвращает текущий обработчик сигнала для сигнала signo. См. "rsignal".

Sighandler_t  rsignal_state(int i)
Sigjmp_buf

Это тип буфера, используемый с Sigsetjmp и Siglongjmp.

Siglongjmp

Эта макрокоманда используется так же, как siglongjmp(), но вызовет традиционную longjmp() если siglongjmp недоступна. См. "HAS_SIGSETJMP".

void  Siglongjmp(jmp_buf env, int val)
SIG_NAME

Этот символ содержит список имён сигналов в порядке номера сигнала. Предназначен для использования как статическая инициализация массива, например так:

char *sig_name[] = { SIG_NAME };

Сигналы в списке разделяются запятыми, и каждый сигнал окружён двойными кавычками. В имени сигнала нет ведущего символа SIG, то есть SIGQUIT известен как "QUIT". Пропуски в номерах сигналов (до NSIG) заполняются NUMnn, и т.д., где nn — фактический номер сигнала (например, NUM37). Номер сигнала для sig_name[i] хранится в sig_num[i]. Последний элемент равен 0 для завершения списка с NULL. Это соответствует 0 в конце списка sig_name_init. Обратите внимание, что эта переменная инициализируется из sig_name_init, а не из sig_name (которая не используется).

SIG_NUM

Этот символ содержит список номеров сигналов в том же порядке, что и список SIG_NAME. Подходит для статической инициализации массива, как в:

int sig_num[] = { SIG_NUM };

Сигналы в списке разделяются запятыми, и индексы в этом списке и в списке SIG_NAME совпадают, поэтому вычисление имени сигнала по номеру или наоборот легко выполняется за счёт небольшого динамического линейного поиска. Повторения допускаются, но перемещаются в конец списка. Номер сигнала, соответствующий sig_name[i] равен sig_number[i]. если (i < NSIG) то sig_number[i] == i. Последний элемент равен 0, что соответствует 0 в конце списка sig_name_init. Обратите внимание, что эта переменная инициализируется из sig_num_init, а не из sig_num (которая не используется).

Sigsetjmp

Эта макрокоманда используется так же, как sigsetjmp(), но вызовет традиционную setjmp() если sigsetjmp недоступна. См. "HAS_SIGSETJMP".

int  Sigsetjmp(jmp_buf env, int savesigs)
SIG_SIZE

Эта переменная содержит количество элементов массивов SIG_NAME и SIG_NUM, за исключением конечного элемента NULL

whichsig
whichsig_pv
whichsig_pvn
whichsig_sv

Все они преобразуют имя сигнала в соответствующий номер сигнала, возвращая -1, если соответствующий номер не найден.

Они отличаются только источником имени сигнала:

whichsig_pv берёт имя из NUL-завершённой строки, начинающейся с sig.

whichsig — это просто другое написание, синоним whichsig_pv.

whichsig_pvn берёт имя из строки, начинающейся с sig, длиной len байтов.

whichsig_sv берёт имя из PV, сохранённого в SV sigsv.

I32  whichsig    (const char *sig)
I32  whichsig_pv (const char *sig)
I32  whichsig_pvn(const char *sig, STRLEN len)
I32  whichsig_sv (SV *sigsv)

Настройка сайта

Эти переменные предоставляют подробности о расположении различных библиотек, пунктах назначения установки и т. д., а также о выбранных вариантах установки

ARCHLIB

Эта переменная, если определена, содержит имя каталога, в который пользователь хочет поместить зависимые от архитектуры общедоступные файлы библиотек для perl5. Чаще всего это локальный каталог, такой как /usr/local/lib. Программы, использующие эту переменную, должны быть готовы к обработке расширения имён файлов. Если ARCHLIB совпадает с PRIVLIB, она не определена, так как, вероятно, программа уже ищет PRIVLIB.

ARCHLIB_EXP

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

ARCHNAME

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

BIN

Этот символ содержит путь к каталогу bin, где будет установлено приложение. Программа должна быть готова к подстановке ~имени.

BIN_EXP

Этот символ содержит результат расширения имени файла для символа BIN, для программ, не желающих выполнять это во время выполнения.

INSTALL_USR_BIN_PERL

Этот символ, если определён, указывает, что Perl также должен быть установлен как /usr/bin/perl.

MULTIARCH

Этот символ, если определён, указывает, что процесс сборки создаст некоторые двоичные файлы, которые будут использоваться в кроссплатформенной среде. Так, например, происходит с «толстыми» двоичными файлами NeXT, которые содержат исполняемые файлы для нескольких CPUs.

PERL_INC_VERSION_LIST

Эта переменная определяет список подкаталогов, в которых perl.c:incpush() и lib/lib.pm будут автоматически искать при добавлении каталогов в @INC, в формате, подходящем для строки инициализации C. См. запись inc_version_list в разделе «Портирование/Глоссарий» для получения дополнительных подробностей.

PERL_OTHERLIBDIRS

Эта переменная содержит набор путей, разделённых двоеточием, для поиска дополнительных файлов библиотек или модулей perl-бинарником. Эти каталоги будут добавлены в конец @INC. Perl будет автоматически искать каталоги, специфичные для версии и архитектуры, ниже каждого пути. См. "PERL_INC_VERSION_LIST" для получения дополнительных подробностей.

PERL_RELOCATABLE_INC

Этот символ, если определён, указывает, что мы хотим перемещать записи в @INC во время выполнения на основе расположения perl-бинарника.

PERL_TARGETARCH

Этот символ, если определён, указывает целевую архитектуру, для которой Perl был скомпилирован в кросс-платформенном режиме. Не определён, если кросс-компиляция не проводилась.

PERL_USE_DEVEL

Этот символ, если определён, указывает, что Perl был сконфигурирован с -Dusedevel, чтобы включить функции разработки. Это не должно использоваться для производственных сборок.

PERL_VENDORARCH

Если определён, этот символ содержит имя частной библиотеки. Библиотека является частной в том смысле, что она не должна быть в пути выполнения любого пользователя, но должна быть доступна для всех. Может иметь ~ в начале. В стандартном дистрибутиве ничего в этом каталоге не будет. Поставщики Perl могут поместить свои собственные зависимости от архитектуры модули и расширения в этот каталог с

MakeMaker Makefile.PL INSTALLDIRS=vendor

или аналогичным. См. INSTALL для получения подробностей.

PERL_VENDORARCH_EXP

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

PERL_VENDORLIB_EXP

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

PERL_VENDORLIB_STEM

Это определение PERL_VENDORLIB_EXP с удалением любого последующего компонента, специфичного для версии. Элементы в inc_version_list (inc_version_list.U (часть метаконфигурации)) могут быть добавлены к этой переменной для создания списка каталогов для поиска.

PRIVLIB

Этот символ содержит имя частной библиотеки для этого пакета. Библиотека является частной в том смысле, что она не должна быть в пути выполнения любого пользователя, но должна быть доступна для всех. Программа должна быть готова к обработке расширения ~.

PRIVLIB_EXP

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

END_OF_DOCUMENT_MARKER
SITEARCH

Этот символ содержит имя приватной библиотеки для данного пакета. Библиотека является приватной в том смысле, что ей не обязательно быть в пути выполнения программы, но она должна быть доступна всему миру. Программа должна быть готова к обработке ~расширений. Стандартная дистрибуция ничего не поместит в этот каталог. После установки perl пользователи могут установить свои собственные локальные модули, зависящие от архитектуры, в этот каталог с

MakeMaker Makefile.PL

или эквивалентом. Подробности см. в INSTALL.

SITEARCH_EXP

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

SITELIB

Этот символ содержит имя приватной библиотеки для данного пакета. Библиотека является приватной в том смысле, что ей не обязательно быть в пути выполнения программы, но она должна быть доступна всему миру. Программа должна быть готова к обработке ~расширений. Стандартная дистрибуция ничего не поместит в этот каталог. После установки perl пользователи могут установить свои собственные локальные независимые от архитектуры модули в этот каталог с

MakeMaker Makefile.PL

или эквивалентом. Подробности см. в INSTALL.

SITELIB_EXP

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

SITELIB_STEM

Это определение равно SITELIB_EXP с удалением любого конечного компонента, специфичного для версии. Элементы в inc_version_list (inc_version_list.U (часть метаконфигурации)) могут быть добавлены к этой переменной для генерации списка каталогов для поиска.

STARTPERL

Эта переменная содержит строку, которую нужно поместить перед скриптом perl, чтобы убедиться (надеемся), что он выполняется с помощью perl, а не какой-то оболочки.

USE_64_BIT_ALL

Если этот символ определен, это означает, что 64-битные целые числа должны использоваться при возможности. Если не определен, будут использоваться родные целые числа (32 или 64 бита). Используется максимальная возможная 64-битная поддержка: LP64 или ILP64, что означает, что вы сможете использовать более 2 гигабайт памяти. Этот режим ещё более бинарно несовместим, чем USE_64_BIT_INT. Возможно, вы не сможете запустить полученный исполняемый файл в 32-битной CPU системе вообще, или вам может потребоваться хотя бы перезагрузить вашу ОС в 64-битный режим.

USE_64_BIT_INT

Если этот символ определен, это означает, что 64-битные целые числа должны использоваться при возможности. Если не определен, будут использоваться родные целые числа (32 или 64 бита). Используется минимальная возможная 64-битная поддержка, только достаточно для включения 64-битных целых чисел в Perl. Это может означать использование, например, "long long", в то время как ваша память всё равно может быть ограничена 2 гигабайтами.

USE_BSD_GETPGRP

Если этот символ определён, это означает, что getpgrp нуждается в одном аргументе, в то время как USG нуждается ни в одном.

USE_BSD_SETPGRP

Если этот символ определен, это означает, что setpgrp нуждается в двух аргументах, в то время как USG нуждается ни в одном. Смотрите также "HAS_SETPGID" для интерфейса POSIX.

USE_C_BACKTRACE

Если этот символ определен, это означает, что Perl должен быть скомпилирован с поддержкой backtrace.

USE_CPLUSPLUS

Если этот символ определен, это означает, что компилятор C++ использовался для компиляции Perl и будет использоваться для компиляции расширений.

USE_CROSS_COMPILE

Если этот символ определен, это означает, что Perl компилируется на другую архитектуру.

USE_DTRACE

Если этот символ определен, это означает, что Perl должен быть скомпилирован с поддержкой DTrace.

USE_DYNAMIC_LOADING

Если этот символ определен, это означает, что доступна динамическая загрузка.

USE_FAST_STDIO

Если этот символ определен, это означает, что Perl должен быть скомпилирован с использованием «быстрого stdio». По умолчанию определен в Perl 5.8 и ранее, затем не определен.

USE_ITHREADS

Если этот символ определен, это означает, что Perl должен быть скомпилирован с использованием реализации многопоточности на основе интерпретатора.

USE_KERN_PROC_PATHNAME

Если этот символ определен, это означает, что мы можем использовать sysctl с KERN_PROC_PATHNAME для получения полного пути к исполняемому файлу и, следовательно, для преобразования $^X в абсолютный путь.

USE_LARGE_FILES

Если этот символ определен, это означает, что должна использоваться поддержка больших файлов при наличии.

USE_LONG_DOUBLE

Если этот символ определен, это означает, что должны использоваться long double при наличии.

USE_MORE_BITS

Если этот символ определен, это означает, что должны использоваться 64-битные интерфейсы и long double при наличии.

USE_NSGETEXECUTABLEPATH

Если этот символ определен, это означает, что мы можем использовать _NSGetExecutablePath и realpath для получения полного пути к исполняемому файлу и, следовательно, для преобразования $^X в абсолютный путь.

USE_PERLIO

Если этот символ определён, это означает, что должна использоваться абстракция PerlIO повсюду. Если не определен, stdio должен использоваться полностью совместимым образом.

USE_QUADMATH

Если этот символ определен, это означает, что должна использоваться библиотека quadmath при её наличии.

USE_REENTRANT_API

Если этот символ определён, это означает, что Perl должен попытаться использовать различные _r версии функций библиотеки. Это чрезвычайно экспериментально.

USE_SEMCTL_SEMID_DS

Если этот символ определён, это означает, что struct semid_ds используется для semctl IPC_STAT.

USE_SEMCTL_SEMUN

Если этот символ определён, это означает, что union semun используется для semctl IPC_STAT.

USE_SITECUSTOMIZE

Если этот символ определён, это означает, что sitecustomize должен использоваться.

USE_SOCKS

Если этот символ определен, это означает, что Perl должен быть скомпилирован с использованием socks.

USE_STAT_BLOCKS

Этот символ определен, если на этой системе структура stat объявляет st_blksize и st_blocks.

USE_STDIO_BASE

Этот символ определен, если поле _base (или подобное) структуры stdio FILE может использоваться для доступа к буферу stdio для дескриптора файла. Если это определено, то макрос FILE_base(fp) также будет определен и должен использоваться для доступа к этому полю. Кроме того, макрос FILE_bufsiz(fp) будет определен и должен использоваться для определения количества байтов в буфере. USE_STDIO_BASE никогда не будет определен, если USE_STDIO_PTR не определен.

USE_STDIO_PTR

Этот символ определен, если поля _ptr и _cnt (или аналогичные) структуры stdio FILE могут использоваться для доступа к буферу stdio для дескриптора файла. Если это определено, то макросы FILE_ptr(fp) и FILE_cnt(fp) также будут определены и должны использоваться для доступа к этим полям.

USE_STRICT_BY_DEFAULT

Если этот символ определен, это активирует дополнительные параметры по умолчанию. В данный момент это только активирует неявственный strict по умолчанию.

USE_THREADS

Если этот символ определен, это означает, что Perl должен быть скомпилирован с использованием потоков. В настоящее время это синоним и USE_ITHREADS, но в конечном итоге исходный код должен быть изменен, чтобы использовать это для обозначения _any_ реализации потоков.

Значения конфигурации сокетов

HAS_SOCKADDR_IN6

Если этот символ определён, это указывает на наличие struct sockaddr_in6;

HAS_SOCKADDR_SA_LEN

Если этот символ определён, это указывает, что структура struct sockaddr имеет член, называемый sa_len, указывающий на длину структуры.

HAS_SOCKADDR_STORAGE

Если этот символ определён, это указывает на наличие struct sockaddr_storage;

HAS_SOCKATMARK

Если этот символ определён, это означает, что процедура sockatmark доступна для проверки, находится ли сокет в режиме внедиапазонной метки.

HAS_SOCKET

Если этот символ определён, это указывает, что интерфейс BSD socket поддерживается.

HAS_SOCKETPAIR

Если этот символ определён, это указывает, что вызов BSD socketpair() поддерживается.

HAS_SOCKS5_INIT

Если этот символ определён, это указывает, что процедура socks5_init доступна для инициализации SOCKS 5.

I_SOCKS

Если этот символ определён, это означает, что socks.h существует и должен быть включён.

#ifdef I_SOCKS
    #include <socks.h>
#endif
I_SYS_SOCKIO

Если этот символ определён, это означает, что sys/sockio.h должен быть включён для получения опций ioctl сокетов, таких как SIOCATMARK. 

#ifdef I_SYS_SOCKIO
    #include <sys_sockio.h>
#endif

Фильтры исходного кода

apply_builtin_cv_attributes

Учитывая список OP_LIST, содержащий определения атрибутов, отфильтруйте его по известным встроенным атрибутам, которые нужно применить к cv, вернув, возможно, меньший список, содержащий только оставшиеся.

OP *  apply_builtin_cv_attributes(CV *cv, OP *attrlist)
filter_add

Описание в perlfilter.

SV *  filter_add(filter_t funcp, SV *datasv)
filter_del

Удалить последний добавленный экземпляр аргумента функции фильтра

void  filter_del(filter_t funcp)
filter_read

Описание в perlfilter.

I32  filter_read(int idx, SV *buf_sv, int maxlen)
scan_vstring

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

Функция должна вызываться так

sv = sv_2mortal(newSV(5));
s = scan_vstring(s,e,sv);

где s и e — начало и конец строки. Переменная sv должна быть достаточно большой, чтобы хранить переданную vстроку, по соображениям производительности.

Эта функция может выдать ошибку, если в области вызова включены предупреждения fatal, поэтому в примере используется sv_2mortal (чтобы предотвратить утечку). Не забудьте выполнить SvREFCNT_inc после этого, если вы используете sv_2mortal.

char *  scan_vstring(const char *s, const char * const e, SV *sv)
start_subparse

Настройка для разбора подпрограммы.

Если is_format не равно нулю, вход должен рассматриваться как подпрограмма формата (специализированная подпрограмма, используемая для реализации функции format Perl); в противном случае — как обычная подпрограмма sub.

flags добавляются к флагам для PL_compcv.

flags может включать бит CVf_IsMETHOD, что делает новую подпрограмму методом.

Функция возвращает значение PL_savestack_ix, которое действовало при входе в функцию;

I32  start_subparse(I32 is_format, U32 flags)

Макросы управления стеком

dMARK

Объявление переменной маркера стека, mark, для XSUB. См. "MARK" и "dORIGMARK". 

dMARK;
dORIGMARK

Сохраняет исходный маркер стека для XSUB. См. "ORIGMARK". 

dORIGMARK;
dSP

Объявляет локальную копию указателя на стек Perl для XSUB, доступную через макрос SP. См. "SP". 

dSP;
dTARGET

Объявляет, что эта функция использует TARG, и инициализирует ее.

dTARGET;
EXTEND

Используется для расширения стека аргументов для значений возврата XSUB. После использования гарантирует, что в стеке есть место для помещения как минимум nitems элементов.

void  EXTEND(SP, SSize_t nitems)
MARK

Переменная маркера стека для XSUB. См. "dMARK".

mPUSHi

Поместить целое число в стек. В стеке должно быть достаточно места для этого элемента. Не использует TARG. См. также "PUSHi", "mXPUSHi" и "XPUSHi". 

void  mPUSHi(IV iv)
mPUSHn

Поместить число с плавающей точкой в стек. В стеке должно быть достаточно места для этого элемента. Не использует TARG. См. также "PUSHn", "mXPUSHn" и "XPUSHn". 

void  mPUSHn(NV nv)
mPUSHp

Поместить строку в стек. В стеке должно быть достаточно места для этого элемента. len указывает длину строки. Не использует TARG. См. также "PUSHp", "mXPUSHp" и "XPUSHp". 

void  mPUSHp(char* str, STRLEN len)
mPUSHpvs

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

void  mPUSHpvs("literal string")
mPUSHs

Поместить SV в стек и сделать SV смертельным. В стеке должно быть достаточно места для этого элемента. Не использует TARG. См. также "PUSHs" и "mXPUSHs". 

void  mPUSHs(SV* sv)
mPUSHu

Поместить целое без знака в стек. В стеке должно быть достаточно места для этого элемента. Не использует TARG. См. также "PUSHu", "mXPUSHu" и "XPUSHu". 

void  mPUSHu(UV uv)
mXPUSHi

Поместить целое число в стек, расширив стек при необходимости. Не использует TARG. См. также "XPUSHi", "mPUSHi" и "PUSHi". 

void  mXPUSHi(IV iv)
mXPUSHn

Поместить число с плавающей точкой в стек, расширив стек при необходимости. Не использует TARG. См. также "XPUSHn", "mPUSHn" и "PUSHn". 

void  mXPUSHn(NV nv)
mXPUSHp

Поместить строку в стек, расширив стек при необходимости. len указывает длину строки. Не использует TARG. См. также "XPUSHp", mPUSHp и PUSHp. 

void  mXPUSHp(char* str, STRLEN len)
mXPUSHpvs

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

void  mXPUSHpvs("literal string")
mXPUSHs

Поместить SV в стек, расширив стек при необходимости и сделав SV смертельным. Не использует TARG. См. также "XPUSHs" и "mPUSHs". 

void  mXPUSHs(SV* sv)
mXPUSHu

Поместить целое без знака в стек, расширив стек при необходимости. Не использует TARG. См. также "XPUSHu", "mPUSHu" и "PUSHu". 

void  mXPUSHu(UV uv)
newXSproto

Используется xsubpp для подключения XSUB как подпрограмм Perl. Добавляет прототипы Perl к подпрограммам.

ORIGMARK

Исходный маркер стека для XSUB. См. "dORIGMARK".

PL_markstack

Описание в perlguts.

PL_markstack_ptr

Описание в perlguts.

PL_savestack

Описание в perlguts.

PL_savestack_ix

Описание в perlguts.

PL_scopestack

Описание в perlguts.

PL_scopestack_ix

Описание в perlguts.

PL_scopestack_name

Описание в perlguts.

PL_stack_base

Описание в perlguts.

PL_stack_sp

Описание в perlguts.

PL_tmps_floor

Описание в perlguts.

PL_tmps_ix

Описание в perlguts.

PL_tmps_stack

Описание в perlguts.

POPi

Извлечь целое число из стека.

IV  POPi
POPl

Извлечь целое число типа long из стека.

long  POPl
POPn

Извлечь число с плавающей точкой из стека.

NV  POPn
POPp

Извлечь строку из стека.

char*  POPp
POPpbytex

Извлечь строку из стека, которая должна состоять из байтов, т.е. символов < 256.

char*  POPpbytex
POPpx

Извлечь строку из стека. Идентично POPp. Два названия по историческим причинам.

char*  POPpx
POPs

Извлечь SV из стека.

SV*  POPs
POPu

Извлечь целое без знака из стека.

UV  POPu
POPul

Извлечь целое без знака типа unsigned long из стека.

long  POPul
PUSHi

Поместить целое число в стек. В стеке должно быть достаточно места для этого элемента. Обрабатывает магию «set». Использует TARG, поэтому следует вызвать dTARGET или dXSTARG, чтобы объявить ее. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mPUSHi" вместо этого. См. также "XPUSHi" и "mXPUSHi". 

void  PUSHi(IV iv)
PUSHMARK

Открывающая скобка для аргументов при обратном вызове. См. "PUTBACK" и perlcall.

void  PUSHMARK(SP)
PUSHmortal

Поместить новый смертный SV в стек. В стеке должно быть достаточно места для этого элемента. Не использует TARG. См. также "PUSHs", "XPUSHmortal" и "XPUSHs". 

void  PUSHmortal
PUSHn

Поместить число с плавающей точкой в стек. В стеке должно быть достаточно места для этого элемента. Обрабатывает магию «set». Использует TARG, поэтому следует вызвать dTARGET или dXSTARG, чтобы объявить ее. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mPUSHn" вместо этого. См. также "XPUSHn" и "mXPUSHn". 

void  PUSHn(NV nv)
PUSHp

Поместить строку в стек. В стеке должно быть достаточно места для этого элемента. len указывает длину строки. Обрабатывает магию «set». Использует TARG, поэтому следует вызвать dTARGET или dXSTARG, чтобы объявить ее. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mPUSHp" вместо этого. См. также "XPUSHp" и "mXPUSHp". 

void  PUSHp(char* str, STRLEN len)
PUSHpvs

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

void  PUSHpvs("literal string")
PUSHs

Поместить SV в стек. В стеке должно быть достаточно места для этого элемента. Не обрабатывает магию «set». Не использует TARG. См. также "PUSHmortal", "XPUSHs", и "XPUSHmortal". 

void  PUSHs(SV* sv)
PUSHu

Поместить целое без знака в стек. В стеке должно быть достаточно места для этого элемента. Обрабатывает магию «set». Использует TARG, поэтому следует вызвать dTARGET или dXSTARG, чтобы объявить ее. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mPUSHu" вместо этого. См. также "XPUSHu" и "mXPUSHu". 

void  PUSHu(UV uv)
END_OF_DOCUMENT_MARKER
PUTBACK

Закрывающая скобка для аргументов XSUB. Обычно обрабатывается xsubpp. См. "PUSHMARK" и perlcall для других применений.

PUTBACK;
SAVEt_INT

Описание в perlguts.

SP

Указатель стека. Обычно обрабатывается xsubpp. См. "dSP" и SPAGAIN.

SPAGAIN

Перезагрузка указателя стека. Используется после обратного вызова. См. perlcall.

SPAGAIN;
SSNEW
SSNEWa
SSNEWat
SSNEWt

Эти макросы временно выделяют данные в стеке сохранений, возвращая индекс SSize_t в стеке сохранений, потому что указатель может быть повреждён, если стек сохранений перемещается при перевыделении. Используйте "SSPTR", чтобы преобразовать возвращённый индекс в указатель.

Различия в формах заключаются в том, что обычный SSNEW выделяет size байтов; SSNEWt и SSNEWat выделяют size объектов, каждый из которых имеет тип type; а <SSNEWa> и SSNEWat гарантируют выравнивание новых данных по границе align. Наиболее полезное значение для выравнивания, вероятно, "MEM_ALIGNBYTES". Выравнивание будет сохранено при перевыделении стека сохранений только если realloc возвращает данные, выровненные по размеру, кратно "align"!

SSize_t  SSNEW  (Size_t size)
SSize_t  SSNEWa (Size_t_size, Size_t align)
SSize_t  SSNEWat(Size_t_size, type, Size_t align)
SSize_t  SSNEWt (Size_t size, type)
SSPTR
SSPTRt

Эти макросы преобразуют index, возвращаемые L/<SSNEW> и подобными макросами, в фактические указатели.

Различие заключается в том, что SSPTR приводит результат к типу type, а SSPTRt приводит его к указателю на тот type тип.

type    SSPTR (SSize_t index, type)
type *  SSPTRt(SSize_t index, type)
TARG

TARG сокращённо от "target". Это запись в стеке, на которую ссылается op_targ оператора. Это рабочее пространство, часто используемое в качестве возвращаемого значения оператора, но некоторые используют его для других целей.

TARG;
TOPs

Описание в perlguts.

XPUSHi

Положить целое число в стек, расширяя его при необходимости. Обрабатывает магию 'set'. Использует TARG, поэтому следует вызвать dTARGET или dXSTARG, чтобы объявить его. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - вместо этого используйте "mXPUSHi". См. также "PUSHi" и "mPUSHi". 

void  XPUSHi(IV iv)
XPUSHmortal

Положить новый смертный SV в стек, расширяя его при необходимости. Не использует TARG. См. также "XPUSHs", "PUSHmortal" и "PUSHs".

void  XPUSHmortal
XPUSHn

Положить число с плавающей точкой в стек, расширяя его при необходимости. Обрабатывает магию 'set'. Использует TARG, поэтому следует вызвать dTARGET или dXSTARG, чтобы объявить его. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - вместо этого используйте "mXPUSHn". См. также "PUSHn" и "mPUSHn".

void  XPUSHn(NV nv)
XPUSHp

Положить строку в стек, расширяя его при необходимости. len указывает длину строки. Обрабатывает магию 'set'. Использует TARG, поэтому следует вызвать dTARGET или dXSTARG, чтобы объявить его. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - вместо этого используйте "mXPUSHp". См. также "PUSHp" и "mPUSHp".

void  XPUSHp(char* str, STRLEN len)
XPUSHpvs

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

void  XPUSHpvs("literal string")
XPUSHs

Положить SV в стек, расширяя его при необходимости. Не обрабатывает магию 'set'. Не использует TARG. См. также "XPUSHmortal", PUSHs и PUSHmortal.

void  XPUSHs(SV* sv)
XPUSHu

Положить беззнаковое целое число в стек, расширяя его при необходимости. Обрабатывает магию 'set'. Использует TARG, поэтому следует вызвать dTARGET или dXSTARG, чтобы объявить его. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - вместо этого используйте "mXPUSHu". См. также "PUSHu" и "mPUSHu".

void  XPUSHu(UV uv)
XS_APIVERSION_BOOTCHECK

Макрос для проверки того, что версия API Perl, с которой был скомпилирован модуль XS, соответствует версии API интерпретатора Perl, в который он загружается.

XS_APIVERSION_BOOTCHECK;
XSRETURN

Возврат из XSUB, указывающий количество элементов в стеке. Обычно обрабатывается xsubpp.

void  XSRETURN(int nitems)
XSRETURN_EMPTY

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

XSRETURN_EMPTY;
XSRETURN_IV

Возвращает целое число из XSUB немедленно. Использует XST_mIV.

void  XSRETURN_IV(IV iv)
XSRETURN_NO

Возвращает &PL_sv_no из XSUB немедленно. Использует XST_mNO.

XSRETURN_NO;
XSRETURN_NV

Возвращает число с плавающей точкой из XSUB немедленно. Использует XST_mNV.

void  XSRETURN_NV(NV nv)
XSRETURN_PV

Возвращает копию строки из XSUB немедленно. Использует XST_mPV.

void  XSRETURN_PV(char* str)
XSRETURN_UNDEF

Возвращает &PL_sv_undef из XSUB немедленно. Использует XST_mUNDEF.

XSRETURN_UNDEF;
XSRETURN_UV

Возвращает целое число из XSUB немедленно. Использует XST_mUV.

void  XSRETURN_UV(IV uv)
XSRETURN_YES

Возвращает &PL_sv_yes из XSUB немедленно. Использует XST_mYES.

XSRETURN_YES;
XST_mIV

Поместить целое число в указанную позицию pos в стеке. Значение хранится в новом смертном SV.

void  XST_mIV(int pos, IV iv)
XST_mNO

Поместить &PL_sv_no в указанную позицию pos в стеке.

void  XST_mNO(int pos)
XST_mNV

Поместить число с плавающей точкой в указанную позицию pos в стеке. Значение хранится в новом смертном SV.

void  XST_mNV(int pos, NV nv)
XST_mPV

Поместить копию строки в указанную позицию pos в стеке. Значение хранится в новом смертном SV.

void  XST_mPV(int pos, char* str)
XST_mUNDEF

Поместить &PL_sv_undef в указанную позицию pos в стеке.

void  XST_mUNDEF(int pos)
XST_mUV

Поместить беззнаковое целое число в указанную позицию pos в стеке. Значение хранится в новом смертном SV.

void  XST_mUV(int pos, UV uv)
XST_mYES

Поместить &PL_sv_yes в указанную позицию pos в стеке.

void  XST_mYES(int pos)
XS_VERSION

Идентификатор версии модуля XS. Обычно обрабатывается автоматически ExtUtils::MakeMaker. См. "XS_VERSION_BOOTCHECK".

XS_VERSION_BOOTCHECK

Макрос для проверки того, что переменная $VERSION модуля PM соответствует переменной XS_VERSION модуля XS. Обычно обрабатывается автоматически xsubpp. См. "The VERSIONCHECK: Keyword" in perlxs.

XS_VERSION_BOOTCHECK;

Обработка строк

См. также "Unicode Support".

CAT2

Этот макрос конкатенирует 2 токена.

token  CAT2(token x, token y)
Copy
CopyD

Интерфейс XSUB для C-функции memcpy. src — источник, dest — назначение, nitems — количество элементов, а type — тип. Может не удаться при перекрывающихся копиях. См. также "Move".

CopyD похож на Copy, но возвращает dest. Полезно для стимулирования оптимизации хвостового вызова компилятором.

void    Copy (void* src, void* dest, int nitems, type)
void *  CopyD(void* src, void* dest, int nitems, type)
delimcpy

Скопировать буфер источника в буфер назначения, остановившись на (но не включая) первой встреченной в источнике неэкранированной (определяется ниже) границе байт delim. Источник — это байты между from и from_end - 1. Аналогично, dest — это to до to_end.

Количество скопированных байтов записывается в *retlen.

Возвращает позицию первого нескопированного delim в буфере from, но если такая позиция не найдена до from_end, возвращается from_end, и весь буфер from .. from_end - 1 копируется.

Если в буфере назначения есть место после копирования, добавляется дополнительный завершающий контрольный NUL байт (не включен в возвращаемую длину).

Ошибка возникает, если буфер назначения недостаточно велик, чтобы вместить всё, что должно быть скопировано. В этом случае значение, большее, чем to_end - to, записывается в *retlen, и столько байтов из источника, сколько поместится, будет записано в назначение. Отсутствие места для контрольного NUL байта не считается ошибкой.

В следующих примерах пусть x — это разделитель, а 0 представляет собой байт NUL (НЕ цифру 0). Тогда у нас будет

 Source     Destination
abcxdef        abc0

при условии, что буфер назначения имеет длину не менее 4 байт.

Экранированный разделитель — это такой, за которым непосредственно следует одиночный обратный слэш. Экранированные разделители копируются, и копирование продолжается после разделителя; обратный слэш не копируется:

 Source       Destination
abc\xdef       abcxdef0

(при условии, что буфер назначения имеет длину не менее 8 байт).

На самом деле это немного сложнее. Последовательность любого нечётного числа обратных слэшей экранирует следующий разделитель, и копирование продолжается с удалением ровно одного обратного слэша.

    Source         Destination
    abc\xdef          abcxdef0
  abc\\\xdef        abc\\xdef0
abc\\\\\xdef      abc\\\\xdef0

(как всегда, если назначение достаточно велико)

Чётное число предшествующих обратных слэшей не экранирует разделитель, поэтому копирование останавливается непосредственно перед ним, и все обратные слэши включаются (без удаления; ноль считается чётным):

    Source         Destination
    abcxdef          abc0
  abc\\xdef          abc\\0
abc\\\\xdef          abc\\\\0
char *  delimcpy(char *to, const char *to_end, const char *from,
                 const char *from_end, const int delim,
                 I32 *retlen)
do_join

Это выполняет операцию Perl join, помещая объединённый результат в sv.

Элементы для объединения находятся в SVs, хранящихся в массиве C указателей на SVs, от **mark до **sp - 1. Таким образом, *mark — ссылка на первый SV. Каждый SV будет преобразован в PV, если это не уже PV.

delim содержит строку (или преобразованную в строку), которая будет отделять каждый из объединённых элементов.

Если какой-либо компонент находится в UTF-8, результат также будет в UTF-8, и все компоненты, не являющиеся UTF-8, будут преобразованы в UTF-8 по мере необходимости.

Обрабатываются магические свойства и затирание.

void  do_join(SV *sv, SV *delim, SV **mark, SV **sp)
do_sprintf

Это выполняет операцию Perl sprintf, помещая строковый результат в sv.

Элементы для форматирования находятся в SVs, хранящихся в массиве C указателей на SVs длиной len> и начиная с **sarg. Элемент, на который ссылается *sarg — это формат.

Обрабатываются магические свойства и затирание.

void  do_sprintf(SV *sv, SSize_t len, SV **sarg)
fbm_compile

Анализирует строку, чтобы сделать быстрый поиск в ней с помощью fbm_instr() — алгоритма Бойера-Мура.

void  fbm_compile(SV *sv, U32 flags)
fbm_instr

Возвращает расположение SV в строке, ограниченной big и bigend (bigend) — символ, следующий за последним символом). Возвращает NULL если строка не найдена. sv не обязательно должно быть fbm_compiled, но тогда поиск будет медленнее.

char *  fbm_instr(unsigned char *big, unsigned char *bigend,
                  SV *littlestr, U32 flags)
foldEQ

Возвращает true, если ведущие len байты строк s1 и s2 совпадают независимо от регистра; в противном случае — false. Прописные и строчные буквы ASCII-диапазона соответствуют друг другу и своим вариантам регистров. Нерегистровые и не-ASCII байты соответствуют только себе.

I32  foldEQ(const char *a, const char *b, I32 len)
ibcmp

Это синоним для (! foldEQ())

I32  ibcmp(const char *a, const char *b, I32 len)
ibcmp_locale

Это синоним для (! foldEQ_locale())

I32  ibcmp_locale(const char *a, const char *b, I32 len)
ibcmp_utf8

Это синоним для (! foldEQ_utf8())

I32  ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1,
                const char *s2, char **pe2, UV l2, bool u2)
instr

То же самое, что и strstr(3), который находит и возвращает указатель на первое вхождение NUL-завершающей подстроки little в NUL-завершающей строке big, возвращая NULL, если не найдено. Завершающие NUL-байты не сравниваются.

char *  instr(const char *big, const char *little)
memCHRs

Возвращает позицию первого вхождения байта c в литеранной строке "list", или NULL, если c не появляется в "list" Все байты рассматриваются как unsigned char. Таким образом, эта макрокоманда может использоваться для определения, входит ли c в набор определенных символов. В отличие от strchr(3), она работает даже если c — это NUL (и набор не включает NUL).

bool  memCHRs("list", char c)
memEQ

Проверяет два буфера (которые могут содержать вложенные NUL символы) на равенство. Параметр len указывает количество байтов для сравнения. Возвращает true или false. Неопределенное поведение, если ни один из буферов не содержит не менее len байтов.

bool  memEQ(char* s1, char* s2, STRLEN len)
memEQs

Как "memEQ", но вторая строка — литеранная строка в двойных кавычках, l1 указывает количество байтов в s1. Возвращает true или false.

bool  memEQs(char* s1, STRLEN l1, "s2")
memNE

Проверяет два буфера (которые могут содержать вложенные NUL символы) на неравенство. Параметр len указывает количество байтов для сравнения. Возвращает true или false. Неопределенное поведение, если ни один из буферов не содержит не менее len байтов.

bool  memNE(char* s1, char* s2, STRLEN len)
memNEs

Как "memNE", но вторая строка — литеранная строка в двойных кавычках, l1 указывает количество байтов в s1. Возвращает true или false.

bool  memNEs(char* s1, STRLEN l1, "s2")
Move
MoveD

Интерфейс XSUB-писателя для C-функции memmove. src — источник, dest — назначение, nitems — количество элементов, и type — тип. Может выполнять перемещение с перекрытием. См. также "Copy".

MoveD подобно Move, но возвращает dest. Полезно для поощрения оптимизации вызовов компилятором.

void    Move (void* src, void* dest, int nitems, type)
void *  MoveD(void* src, void* dest, int nitems, type)
my_snprintf

Функциональность библиотеки C snprintf, если доступна и соответствует стандарту (использует vsnprintf, фактически). Однако, если vsnprintf недоступна, к сожалению, будет использована небезопасная функция vsprintf, которая может перезаписать буфер (есть проверка переполнения, но она может быть слишком поздней). Рассмотрите использование sv_vcatpvf вместо этого или получение vsnprintf.

int  my_snprintf(char *buffer, const Size_t len,
                 const char *format, ...)
my_sprintf

DEPRECATED! Планируется удалить my_sprintf из будущей версии Perl. Не используйте её в новом коде; удалите её из существующего кода.

НЕ используйте её из-за возможности переполнения buffer. Используйте вместо этого my_snprintf()

int  my_sprintf(NN char *buffer, NN const char *pat, ...)
my_strnlen

Функция библиотеки C strnlen, если доступна, или её реализация в Perl.

my_strnlen() вычисляет длину строки до maxlen символов. Она никогда не попытается обратиться к большему количеству чем maxlen символов, что делает её пригодной для использования со строками, которые не гарантированно завершаются NUL.

Size_t  my_strnlen(const char *str, Size_t maxlen)
my_vsnprintf

Функция библиотеки C vsnprintf, если доступна и соответствует стандарту. Однако, если vsnprintf недоступна, к сожалению, будет использована небезопасная функция vsprintf, которая может перезаписать буфер (есть проверка переполнения, но она может быть слишком поздней). Рассмотрите использование sv_vcatpvf вместо этого или получение vsnprintf.

int  my_vsnprintf(char *buffer, const Size_t len,
                  const char *format, va_list ap)
NewCopy

Объединяет Newx() и Copy() в одну макрокоманду. Dest будет выделен с помощью Newx(), а затем src будет скопирован в него.

void  NewCopy(void* src, void* dest, int nitems, type)
ninstr

Найти первое (самое левое) вхождение последовательности байтов в другой последовательности. Это версия Perl функции strstr(), расширенная для обработки произвольных последовательностей, потенциально содержащих вложенные NUL символы (NUL — то, что обозначает начальное n в имени функции; некоторые системы имеют эквивалент, memmem(), но с несколько другим API).

Другой способ понять эту функцию — это поиск иглы в стоге сена. big указывает на первый байт в стоге сена. big_end указывает на байт после последнего байта в стоге сена. little указывает на первый байт в игле. little_end указывает на байт после последнего байта в игле. Все параметры должны быть не-NULL.

Функция возвращает NULL если вхождение little в big отсутствует. Если little — пустая строка, возвращается big.

Поскольку эта функция работает на уровне байтов, и из-за свойств UTF-8 (или UTF-EBCDIC), она будет работать правильно, если игла и стог сена — строки с одинаковым типом UTF-8, но не если типы UTF-8 отличаются.

char *  ninstr(const char *big, const char *bigend,
               const char *little, const char *lend)
Nullch

Указатель на символ-ноль. (Больше недоступен, когда PERL_CORE определен.)

PL_na

Переменная-буфер, в которой хранится значение STRLEN. Было бы лучше назвать её чем-то вроде PL_temp_strlen.

Обычно используется с SvPV, когда планируется отбросить возвращаемую длину (отсюда и длина "Не применимо", откуда и название переменной).

НО ОСТОРОЖНО, если она используется в ситуации, когда что-то, использующее её, находится в стеке вызовов вместе с чем-то другим, использующим её, эта переменная может быть перезаписана, что приведёт к трудно диагностируемым ошибкам.

Обычно более эффективно либо объявить локальную переменную, либо использовать макрос SvPV_nolen.

STRLEN  PL_na
rninstr

Подобно "ninstr", но вместо этого находит последнее (самое правое) вхождение последовательности байтов в другой последовательности, возвращая NULL, если такого вхождения нет.

char *  rninstr(const char *big, const char *bigend,
                const char *little, const char *lend)
savepv

Версия Perl для strdup(). Возвращает указатель на вновь выделенную строку, которая является дубликатом pv. Размер строки определяется strlen(), что означает, что она может не содержать вложенных NUL символов и должна иметь завершающий NUL символ. Для предотвращения утечек памяти выделенную память для новой строки необходимо освободить, когда она больше не нужна. Это можно сделать с помощью функции "Safefree", или SAVEFREEPV.

На некоторых платформах, например, Windows, вся выделенная память, принадлежащая потоку, освобождается при завершении этого потока. Поэтому, если вам нужно, чтобы этого не происходило, вам необходимо использовать функции общей памяти, такие как "savesharedpv".

char *  savepv(const char *pv)
savepvn

Версия Perl того, чем бы был strndup() в случае его существования. Возвращает указатель на вновь выделенную строку, которая является дубликатом первых len байтов из pv, плюс завершающий NUL байт. Выделенную память для новой строки можно освободить с помощью функции Safefree().

На некоторых платформах, например, Windows, вся выделенная память, принадлежащая потоку, освобождается при завершении этого потока. Поэтому, если вам нужно, чтобы этого не происходило, вам необходимо использовать функции общей памяти, такие как "savesharedpvn".

char *  savepvn(const char *pv, Size_t len)
savepvs

Подобно savepvn, но принимает литеральную строку вместо пары строка/длина.

char*  savepvs("literal string")
savesharedpv

Версия savepv(), которая выделяет дубликат строки в памяти, которая общая для потоков.

char *  savesharedpv(const char *pv)
savesharedpvn

Версия savepvn(), которая выделяет дубликат строки в памяти, общей для потоков. (С конкретным отличием, что указатель NULL не приемлем)

char *  savesharedpvn(const char * const pv, const STRLEN len)
savesharedpvs

Версия savepvs(), которая выделяет дубликат строки в памяти, общей для потоков.

char*  savesharedpvs("literal string")
savesharedsvpv

Версия savesharedpv(), которая выделяет дубликат строки в памяти, общей для потоков.

char *  savesharedsvpv(SV *sv)
savesvpv

Версия savepv()/savepvn(), которая получает строку для дублирования из переданного SV, используя SvPV()

На некоторых платформах, например, Windows, вся выделенная память, принадлежащая потоку, освобождается при завершении этого потока. Поэтому, если вам нужно, чтобы этого не происходило, вам необходимо использовать функции общей памяти, такие как "savesharedsvpv".

char *  savesvpv(SV *sv)
strEQ

Проверка двух строк, завершенных символом NUL, на равенство. Возвращает true или false.

bool  strEQ(char* s1, char* s2)
strGE

Проверка двух строк, завершенных символом NUL, на то, больше ли первая, s1, или равна второй, s2. Возвращает true или false.

bool  strGE(char* s1, char* s2)
strGT

Проверка двух строк, завершенных символом NUL, на то, больше ли первая, s1, второй, s2. Возвращает true или false.

bool  strGT(char* s1, char* s2)
STRINGIFY

Этот макрос окружает свой токен двойными кавычками.

string  STRINGIFY(token x)
strLE

Проверка двух строк, завершенных символом NUL, на то, меньше ли первая, s1, или равна второй, s2. Возвращает true или false.

bool  strLE(char* s1, char* s2)
STRLEN

Описание в perlguts.

strLT

Проверка двух строк, завершенных символом NUL, на то, меньше ли первая, s1, второй, s2. Возвращает true или false.

bool  strLT(char* s1, char* s2)
strNE

Проверка двух строк, завершенных символом NUL, на различие. Возвращает true или false.

bool  strNE(char* s1, char* s2)
strnEQ

Проверка двух строк, завершенных символом NUL, на равенство. Параметр len указывает количество байтов для сравнения. Возвращает true или false. (Обёртка для strncmp).

bool  strnEQ(char* s1, char* s2, STRLEN len)
strnNE

Проверка двух строк, завершенных символом NUL, на различие. Параметр len указывает количество байтов для сравнения. Возвращает true или false. (Обёртка для strncmp).

bool  strnNE(char* s1, char* s2, STRLEN len)
STR_WITH_LEN

Возвращает две разделенные запятыми части ввода: литеральную строку и её длину. Это удобный макрос, который помогает при вызовах некоторых API. Обратите внимание, что он не может использоваться в качестве аргумента макросам или функциям, которые в некоторых конфигурациях могут быть макросами, что означает, что для любых вызовов API, где он используется, требуется полная форма Perl_xxx(aTHX_ ...).

pair  STR_WITH_LEN("literal string")
Zero
ZeroD

Интерфейс XSUB-писателя к C-функции memzero. dest — это пункт назначения, nitems — количество элементов, а type — тип.

ZeroD подобен Zero, но возвращает dest. Полезно для поощрения оптимизации вызовов функций компиляторами.

void    Zero (void* dest, int nitems, type)
void *  ZeroD(void* dest, int nitems, type)

Флаги SV

SVt_IV

Флаг типа для скаляров. См. "svtype".

SVt_NULL

Флаг типа для скаляров. См. "svtype".

SVt_NV

Флаг типа для скаляров. См. "svtype".

SVt_PV

Флаг типа для скаляров. См. "svtype".

SVt_PVAV

Флаг типа для массивов. См. "svtype".

SVt_PVCV

Флаг типа для подпрограмм. См. "svtype".

SVt_PVFM

Флаг типа для форматов. См. "svtype".

SVt_PVGV

Флаг типа для typeglob. См. "svtype".

SVt_PVHV

Флаг типа для хэшей. См. "svtype".

SVt_PVIO

Флаг типа для объектов ввода/вывода. См. "svtype".

SVt_PVIV

Флаг типа для скаляров. См. "svtype".

SVt_PVLV

Флаг типа для скаляров. См. "svtype".

SVt_PVMG

Флаг типа для скаляров. См. "svtype".

SVt_PVNV

Флаг типа для скаляров. См. "svtype".

SVt_PVOBJ

ПРИМЕЧАНИЕ: SVt_PVOBJ — экспериментальная функция и может быть изменена или удалена без предварительного уведомления.

Флаг типа для экземпляров объектов. См. "svtype".

SVt_REGEXP

Флаг типа для регулярных выражений. См. "svtype".

svtype

Перечисление флагов типов Perl. Они находятся в файле sv.h в svtype перечислении. Проверьте эти флаги с помощью макроса SvTYPE.

Типы:

SVt_NULL
SVt_IV
SVt_NV
SVt_RV
SVt_PV
SVt_PVIV
SVt_PVNV
SVt_PVMG
SVt_INVLIST
SVt_REGEXP
SVt_PVGV
SVt_PVLV
SVt_PVAV
SVt_PVHV
SVt_PVCV
SVt_PVFM
SVt_PVIO
SVt_PVOBJ

Их проще всего объяснить снизу вверх.

SVt_PVOBJ предназначен для экземпляров объектов нового типа `use feature 'class'`. SVt_PVIO предназначен для объектов ввода-вывода, SVt_PVFM — для форматов, SVt_PVCV — для подпрограмм, SVt_PVHV — для хешей и SVt_PVAV — для массивов.

Все остальные — скалярные типы, то есть вещи, которые можно привязать к переменной $. Для них внутренние типы в основном ортогональны типам языка Perl.

Поэтому проверка SvTYPE(sv) < SVt_PVAV — лучший способ определить, является ли что-то скалярным.

SVt_PVGV представляет собой типглоб. Если !SvFAKE(sv), то это настоящий, непереводимый типглоб. Если SvFAKE(sv), то это скаляр, которому был назначен типглоб. Повторное присвоение ему прекратит его типглобность. SVt_PVLV представляет скаляр, который делегирует другую скалярную величину за кулисами. Он используется, например, для возвращаемого значения substr и для привязанных элементов хешей и массивов. Он может содержать любое скалярное значение, включая типглоб. SVt_REGEXP предназначен для регулярных выражений. SVt_INVLIST предназначен только для внутреннего использования ядра Perl.

SVt_PVMG представляет собой «обычный» скаляр (не типглоб, регулярное выражение или делегат). Поскольку большинству скаляров не нужны все внутренние поля PVMG, мы экономим память, выделяя более мелкие структуры, когда это возможно. Все остальные типы — это просто более простые формы SVt_PVMG, с меньшим количеством внутренних полей. SVt_NULL может содержать только undef. SVt_IV может содержать undef, целое число или ссылку. (SVt_RV — псевдоним для SVt_IV, который существует для обратной совместимости.) SVt_NV может содержать undef или двойное значение. (В сборках, поддерживающих NVs без головы, эти значения также могут содержать ссылку через соответствующий смещение, так же, как и SVt_IV, но эта функция не поддерживается и кажется редким случаем использования.) SVt_PV может содержать undef, строку или ссылку. SVt_PVIV является супермножеством SVt_PV и SVt_IV. SVt_PVNV является супермножеством SVt_PV и SVt_NV. SVt_PVMG может содержать всё, что может содержать SVt_PVNV, но также может быть благословлён или магическим.

Обработка SV

AV_FROM_REF
CV_FROM_REF
HV_FROM_REF

Макросы *V_FROM_REF извлекают SvRV() из заданной ссылки SV и возвращают соответствующе отформатированный указатель на ссылку SV. При работе в -DDEBUGGING, также применяются утверждения, проверяющие, что ref определённо является ссылкой SV, которая ссылается на SV правильного типа.

AV *  AV_FROM_REF(SV * ref)
CV *  CV_FROM_REF(SV * ref)
HV *  HV_FROM_REF(SV * ref)
BOOL_INTERNALS_sv_isbool

Проверяет, является ли SvBoolFlagsOK() sv булевым значением. Обратите внимание, что ответственность за обеспечение того, что sv является SvBoolFlagsOK() перед вызовом этой функции, лежит на вызывающей стороне. Это полезно только в специализированной логике, например, в коде сериализации, где критична производительность, и флаги уже проверены на корректность. Практически всегда следует использовать sv_isbool(sv).

bool  BOOL_INTERNALS_sv_isbool(SV* sv)
BOOL_INTERNALS_sv_isbool_false

Проверяет, является ли SvBoolFlagsOK() sv ложным булевым значением. Обратите внимание, что ответственность за обеспечение того, что sv является SvBoolFlagsOK() перед вызовом этой функции, лежит на вызывающей стороне. Это полезно только в специализированной логике, например, в коде сериализации, где критична производительность, и флаги уже проверены на корректность. Не следует использовать эту функцию для проверки, является ли SV «ложным», для этого следует использовать !SvTRUE(sv).

bool  BOOL_INTERNALS_sv_isbool_false(SV* sv)
BOOL_INTERNALS_sv_isbool_true

Проверяет, является ли SvBoolFlagsOK() sv истинным булевым значением. Обратите внимание, что ответственность за обеспечение того, что sv является SvBoolFlagsOK() перед вызовом этой функции, лежит на вызывающей стороне. Это полезно только в специализированной логике, например, в коде сериализации, где критична производительность, и флаги уже проверены на корректность. Не следует использовать эту функцию для проверки, является ли SV «истинным», для этого следует использовать SvTRUE(sv).

bool  BOOL_INTERNALS_sv_isbool_true(SV* sv)
boolSV

Возвращает SV, равный true, если b имеет истинное значение, или SV, равный false, если b равно 0.

См. также "PL_sv_yes" и "PL_sv_no". 

SV *  boolSV(bool b)
croak_xs_usage

Специализированная версия croak() для вывода сообщения об использовании для xsubs

croak_xs_usage(cv, "eee_yow");

определяет имя пакета и имя подпрограммы из cv, а затем вызывает croak(). Таким образом, если cv равно &ouch::awk, она вызовет croak как:

Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
                                                    "eee_yow");
void  croak_xs_usage(const CV * const cv,
                     const char * const params)
DEFSV

Возвращает SV, связанный с $_. 

SV *  DEFSV
DEFSV_set

Связывает sv с $_. 

void  DEFSV_set(SV * sv)
get_sv

Возвращает SV указанной Perl-скалярной переменной. flags передаются в "gv_fetchpv". Если GV_ADD установлено, и Perl-переменная не существует, она будет создана. Если flags равно нулю, и переменная не существует, возвращается NULL.

ПРИМЕЧАНИЕ: форма perl_get_sv() устарела.

SV *  get_sv(const char *name, I32 flags)
isGV_with_GP

Возвращает булево значение, указывающее, является ли sv GV с указателем на GP (указатель на типглоб).

bool  isGV_with_GP(SV * sv)
looks_like_number

Проверяет, выглядит ли содержимое SV как число (или является ли оно числом). Inf и Infinity обрабатываются как числа (не выдают предупреждений о нечисловых значениях), даже если ваш atof() их не распознаёт. Магия получения игнорируется.

I32  looks_like_number(SV * const sv)
MUTABLE_AV
MUTABLE_CV
MUTABLE_GV
MUTABLE_HV
MUTABLE_IO
MUTABLE_PTR
MUTABLE_SV

Макросы MUTABLE_*() преобразуют указатели к указанным типам таким образом (если компилятор позволяет), что отбрасывание константности вызовет предупреждение, например:

const SV *sv = ...;
AV *av1 = (AV*)sv;        <== BAD:  the const has been silently
                                    cast away
AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn

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

AV *    MUTABLE_AV (AV * p)
CV *    MUTABLE_CV (CV * p)
GV *    MUTABLE_GV (GV * p)
HV *    MUTABLE_HV (HV * p)
IO *    MUTABLE_IO (IO * p)
void *  MUTABLE_PTR(void * p)
SV *    MUTABLE_SV (SV * p)
newRV
newRV_inc

Они идентичны. Они создают обёртку RV для SV. Счётчик ссылок для исходного SV увеличивается.

SV *  newRV(SV * const sv)
newRV_noinc

Создаёт обёртку RV для SV. Счётчик ссылок для исходного SV не увеличивается.

SV *  newRV_noinc(SV * const tmpRef)
newSV

Создаёт новый SV. ненулевое значение параметра len указывает количество предварительно выделенного места в байтах для строкового пространства SV. Также зарезервирован дополнительный байт для завершающего NUL. (SvPOK не задаётся для SV, даже если выделяется строковое пространство.) Счётчик ссылок для нового SV устанавливается в 1.

В версии 5.9.3 макрос newSV() заменяет более старую API NEWSV(), и отбрасывает первый параметр x — вспомогательное средство отладки, которое позволяло вызывающим сторонам идентифицировать себя. Это вспомогательное средство было заменено новым параметром сборки, PERL_MEM_LOG (см. "PERL_MEM_LOG" в perlhacktips). Более старая API всё ещё доступна для использования в модулях XS, поддерживающих более старые версии Perl.

SV *  newSV(const STRLEN len)
newSVbool

Создаёт новый булевый SV.

SV *  newSVbool(const bool bool_val)
newSV_false

Создаёт новый SV, являющийся булевым значением false.

SV *  newSV_false()
newSVhek

Создаёт новый SV из структуры ключа хеша. Возможна генерация скаляров, ссылающихся на общую таблицу строк. Возвращает новый (неопределённый) SV, если hek равно NULL.

SV *  newSVhek(const HEK * const hek)
newSVhek_mortal

Создаёт новый временный SV из структуры ключа хеша. Возможна генерация скаляров, ссылающихся на общую таблицу строк. Возвращает новый (неопределённый) SV, если hek равно NULL.

Это более эффективно, чем sv_2mortal(newSVhek( ... ))

SV *  newSVhek_mortal(const HEK * const hek)
newSViv

Создаёт новый SV и копирует в него целое число. Счётчик ссылок SV устанавливается в 1.

SV *  newSViv(const IV i)
newSVnv

Создаёт новый SV и копирует в него значение с плавающей точкой. Счётчик ссылок SV устанавливается в 1.

SV *  newSVnv(const NV n)
newSVpadname

ПРИМЕЧАНИЕ: newSVpadname является экспериментальной функцией и может быть изменена или удалена без предварительного уведомления.

Создаёт новый SV, содержащий имя блока.

SV*  newSVpadname(PADNAME *pn)
newSVpv

Создаёт новый SV и копирует в него строку (которая может содержать NUL (\0)-символы) в него. Счётчик ссылок SV устанавливается в 1. Если len равно нулю, Perl вычисляет длину с помощью strlen(), (что означает, что если вы используете этот вариант, то s не может содержать встроенные NUL символы и должен иметь завершающий NUL байт).

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

Использование "newSVpvn" — более безопасная альтернатива для строк, не завершающихся NUL. Для строковых литералов используйте "newSVpvs" вместо этого. Эта функция будет работать нормально для строк, завершающихся NUL, но если вы хотите избежать проверки, следует ли вызывать strlen, используйте newSVpvn вместо этого (вызвав strlen самостоятельно).

SV *  newSVpv(const char * const s, const STRLEN len)
newSVpvf

Создаёт новый SV и инициализирует его строкой, отформатированной как sv_catpvf.

ПРИМЕЧАНИЕ: newSVpvf должен быть явно вызван как Perl_newSVpvf с параметром aTHX_. 

SV *  Perl_newSVpvf(pTHX_ const char * const pat, ...)
END_OF_DOCUMENT_MARKER
newSVpvf_nocontext

Как "newSVpvf", но не принимает контекст потока (aTHX) параметр, поэтому используется в ситуациях, когда вызывающая сторона не имеет контекст потока.

SV *  newSVpvf_nocontext(const char * const pat, ...)
newSVpvn

Создаёт новый SV и копирует в него строку, которая может содержать NUL символы (\0) и другие двоичные данные. Счётчик ссылок для SV устанавливается в 1. Обратите внимание, что если len равно нулю, Perl создаст строку нулевой длины (Perl). Вы несёте ответственность за обеспечение того, что исходный буфер имеет длину не менее len байтов. Если параметр buffer равен NULL, новый SV будет неопределённым.

SV *  newSVpvn(const char * const buffer, const STRLEN len)
newSVpvn_flags

Создаёт новый SV и копирует в него строку (которая может содержать NUL (\0) символы). Счётчик ссылок для SV устанавливается в 1. Обратите внимание, что если len равно нулю, Perl создаст строку нулевой длины. Вы несёте ответственность за обеспечение того, что исходная строка имеет длину не менее len байтов. Если параметр s равен NULL, новый SV будет неопределённым. В настоящее время принимаются только флаги SVf_UTF8 и SVs_TEMP. Если SVs_TEMP установлен, то sv_2mortal() вызывается для результата перед возвратом. Если SVf_UTF8 установлен, s считается UTF-8, и флаг SVf_UTF8 будет установлен для нового SV. newSVpvn_utf8() — это удобная обертка для этой функции, определённая как

#define newSVpvn_utf8(s, len, u)			\
    newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
SV *  newSVpvn_flags(const char * const s, const STRLEN len,
                     const U32 flags)
newSVpvn_share

Создаёт новый SV, у которого SvPVX_const указывает на общую строку в таблице строк. Если строка ещё не существует в таблице, она создаётся сначала. Включает флаг SvIsCOW (или READONLY и FAKE в версиях 5.16 и более ранних). Если параметр hash отличен от нуля, используется это значение; в противном случае вычисляется хеш. Хеш строки позже можно получить из SV с помощью макроса "SvSHARED_HASH". Идея в том, что, поскольку таблица строк используется для общих ключей хеша, эти строки будут иметь SvPVX_const == HeKEY, и поиск по хешу позволит избежать сравнения строк.

SV *  newSVpvn_share(const char *s, I32 len, U32 hash)
newSVpvn_utf8

Создаёт новый SV и копирует в него строку (которая может содержать NUL (\0) символы). Если utf8 равно true, вызывается SvUTF8_on для нового SV. Реализован как обертка вокруг newSVpvn_flags. 

SV*  newSVpvn_utf8(const char* s, STRLEN len, U32 utf8)
newSVpvs

Аналогично newSVpvn, но принимает строку-литерал вместо пары строка/длина.

SV*  newSVpvs("literal string")
newSVpvs_flags

Аналогично newSVpvn_flags, но принимает строку-литерал вместо пары строка/длина.

SV*  newSVpvs_flags("literal string", U32 flags)
newSVpv_share

Аналогично newSVpvn_share, но принимает строку, завершённую нулём, вместо пары строка/длина.

SV *  newSVpv_share(const char *s, U32 hash)
newSVpvs_share

Аналогично newSVpvn_share, но принимает строку-литерал вместо пары строка/длина и опускает параметр хеша.

SV*  newSVpvs_share("literal string")
newSVrv

Создаёт новый SV для существующего RV, rv, на который он будет указывать. Если rv не является RV, он будет преобразован в него. Если classname не равен null, новый SV будет благословлён в указанном пакете. Новый SV возвращается, и его счётчик ссылок равен 1. Счётчик ссылок 1 принадлежит rv. См. также newRV_inc() и newRV_noinc() для правильного создания нового RV.

SV *  newSVrv(SV * const rv, const char * const classname)
newSVsv
newSVsv_flags
newSVsv_nomg

Эти функции создают новый SV, являющийся точной копией исходного SV (используя sv_setsv).

Они отличаются только тем, что newSVsv выполняет магию 'get'; newSVsv_nomg пропускает магию; и newSVsv_flags позволяет явно задать параметр flags. 

SV *  newSVsv      (SV * const old)
SV *  newSVsv_flags(SV * const old, I32 flags)
SV *  newSVsv_nomg (SV * const old)
newSV_true

Создаёт новый SV, представляющий собой логическое значение true.

SV *  newSV_true()
newSV_type

Создаёт новый SV указанного типа. Счётчик ссылок для нового SV устанавливается в 1.

SV *  newSV_type(const svtype type)
newSV_type_mortal

Создаёт новый смертный SV указанного типа. Счётчик ссылок для нового SV устанавливается в 1.

Это эквивалентно SV* sv = sv_2mortal(newSV_type(<some type>)) и SV* sv = sv_newmortal(); sv_upgrade(sv, <some_type>) , но должно быть эффективнее обоих. (Если sv_2mortal будет в какой-то момент встроен в код.)

SV *  newSV_type_mortal(const svtype type)
newSVuv

Создаёт новый SV и копирует в него целое беззнаковое число. Счётчик ссылок для SV устанавливается в 1.

SV *  newSVuv(const UV u)
Nullsv

Указатель на SV со значением NULL. (Больше не доступен, когда PERL_CORE определён.)

PL_sv_no

Это SV "newSVpvf". Он является только для чтения. См. "PL_sv_yes". Всегда ссылайтесь на него как на &PL_sv_no. 

SV  PL_sv_no
PL_sv_undef

Это SV undef. Он является только для чтения. Всегда ссылайтесь на него как на &PL_sv_undef. 

SV  PL_sv_undef
PL_sv_yes

Это SV true. Он является только для чтения. См. "PL_sv_no". Всегда ссылайтесь на него как на &PL_sv_yes. 

SV  PL_sv_yes
PL_sv_zero

Этот SV только для чтения имеет нулевое числовое значение и строковое значение "0". Он похож на "PL_sv_no", но отличается своим строковым значением. Может использоваться как быстрая альтернатива mXPUSHi(0), например. Всегда ссылайтесь на него как на &PL_sv_zero. Введён в 5.28.

SV  PL_sv_zero
SAVE_DEFSV

Локализует $_. См. "Локализация изменений" в perlguts.

void  SAVE_DEFSV
sortsv

Сортировка массива указателей SV на месте с помощью заданной функции сравнения.

В настоящее время всегда используется слиянием. См. "sortsv_flags" для более гибкой функции.

void  sortsv(SV **array, size_t num_elts, SVCOMPARE_t cmp)
sortsv_flags

Сортировка массива указателей SV на месте с помощью заданной функции сравнения с различными опциями флагов SORTf_*. 

void  sortsv_flags(SV **array, size_t num_elts, SVCOMPARE_t cmp,
                   U32 flags)
SV

Описание в perlguts.

SvAMAGIC

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

bool  SvAMAGIC(SV * sv)
SvAMAGIC_off

Указывает, что перегрузка (активная магия) отключена для sv. 

void  SvAMAGIC_off(SV *sv)
SvAMAGIC_on

Указывает, что перегрузка (активная магия) включена для sv. 

void  SvAMAGIC_on(SV *sv)
sv_backoff

Удаляет любой смещение строки. Обычно следует использовать макрос-обёртку SvOOK_off.

void  sv_backoff(SV * const sv)
sv_bless

Благословляет SV в указанный пакет. SV должен быть RV. Пакет должен быть обозначен своим хранилищем (см. "gv_stashpv"). Счётчик ссылок SV не меняется.

SV *  sv_bless(SV * const sv, HV * const stash)
SvBoolFlagsOK

Возвращает булево значение, указывающее, установлены ли для SV правильные флаги, чтобы было безопасно вызвать BOOL_INTERNALS_sv_isbool() или BOOL_INTERNALS_sv_isbool_true() или BOOL_INTERNALS_sv_isbool_false(). В настоящее время эквивалентно SvIandPOK(sv) или SvIOK(sv) && SvPOK(sv). Модуль сериализации может захотеть разложить эту проверку. В этом случае настоятельно рекомендуется добавить код, подобный assert(SvBoolFlagsOK(sv)); перед вызовом с использованием любых макросов BOOL_INTERNALS.

U32  SvBoolFlagsOK(SV* sv)
sv_catpv
sv_catpv_flags
sv_catpv_mg
sv_catpv_nomg

Эти функции конкатенируют строку, завершённую нулём, sstr к концу строки в SV. Если SV имеет установленный флаг UTF-8, то присоединённые байты должны быть валидными UTF-8.

Они отличаются только тем, как они обрабатывают магию:

sv_catpv_mg выполняет магию 'get' и 'set'.

sv_catpv выполняет только магию 'get'.

sv_catpv_nomg пропускает всю магию.

sv_catpv_flags имеет дополнительный параметр flags, который позволяет указать любые комбинации обработки магии (используя SV_GMAGIC и/или SV_SMAGIC), а также переопределить обработку UTF-8. Указав флаг SV_CATUTF8, вы заставите интерпретировать присоединённую строку как UTF-8; указав вместо этого флаг SV_CATBYTES, вы интерпретируете её как обычные байты. SV или присоединённая строка будут преобразованы в UTF-8, если необходимо.

void  sv_catpv      (SV * const dsv, const char *sstr)
void  sv_catpv_flags(SV *dsv, const char *sstr, const I32 flags)
void  sv_catpv_mg   (SV * const dsv, const char * const sstr)
void  sv_catpv_nomg (SV * const dsv, const char *sstr)
sv_catpvf
sv_catpvf_mg
sv_catpvf_mg_nocontext
sv_catpvf_nocontext

Эти функции обрабатывают свои аргументы как sprintf, и добавляют отформатированный вывод в SV. Как и sv_vcatpvfn, переупорядочивание аргументов не поддерживается, когда вызывается с непустым списком аргументов C-стиля.

Если добавленные данные содержат символы «wide» (включая, но не ограничиваясь, SVs с PV UTF-8, отформатированным с %s, и символами >255, отформатированными с %c), исходный SV может быть преобразован в UTF-8.

Если исходный SV был UTF-8, шаблон должен быть валидным UTF-8; если исходный SV был набором байтов, шаблон тоже.

Все выполняют магию 'get', но только sv_catpvf_mg и sv_catpvf_mg_nocontext выполняют магию 'set'.

sv_catpvf_nocontext и sv_catpvf_mg_nocontext не принимают параметр контекста потока (aTHX), поэтому используются в ситуациях, когда у вызывающей стороны уже есть контекст потока.

ПРИМЕЧАНИЕ: sv_catpvf должен быть явно вызван как Perl_sv_catpvf с параметром aTHX_.

ПРИМЕЧАНИЕ: sv_catpvf_mg должен быть явно вызван как Perl_sv_catpvf_mg с параметром aTHX_. 

void  Perl_sv_catpvf        (pTHX_ SV * const sv,
                             const char * const pat, ...)
void  Perl_sv_catpvf_mg     (pTHX_ SV * const sv,
                             const char * const pat, ...)
void  sv_catpvf_mg_nocontext(SV * const sv,
                             const char * const pat, ...)
void  sv_catpvf_nocontext   (SV * const sv,
                             const char * const pat, ...)
sv_catpvn
sv_catpvn_flags
sv_catpvn_mg
sv_catpvn_nomg

Эти функции конкатенируют len байтов строки, начиная с ptr, в конец строки, которая находится в dsv. Вызывающая сторона должна убедиться, что ptr содержит не менее len байтов.

Для всех функций, кроме sv_catpvn_flags, предполагается, что добавляемая строка является корректной UTF-8, если у SV установлен статус UTF-8, и строка байтов в противном случае.

Они отличаются тем, что:

sv_catpvn_mg выполняет как «get», так и «set» магию над dsv.

sv_catpvn выполняет только магию «get».

sv_catpvn_nomg пропускает всю магию.

sv_catpvn_flags имеет дополнительный параметр flags, который позволяет указать любую комбинацию обработки магии (используя SV_GMAGIC и/или SV_SMAGIC) и переопределить обработку UTF-8. Передавая флаг SV_CATBYTES, добавляемая строка интерпретируется как обычные байты; передавая вместо этого флаг SV_CATUTF8, она будет интерпретироваться как UTF-8, а dsv будет преобразовано в UTF-8 при необходимости.

sv_catpvn, sv_catpvn_mg, и sv_catpvn_nomg реализованы с использованием sv_catpvn_flags.

void  sv_catpvn      (SV *dsv, const char *sstr, STRLEN len)
void  sv_catpvn_flags(SV * const dsv, const char *sstr,
                      const STRLEN len, const I32 flags)
void  sv_catpvn_mg   (SV *dsv, const char *sstr, STRLEN len)
void  sv_catpvn_nomg (SV *dsv, const char *sstr, STRLEN len)
sv_catpvs

Как и sv_catpvn, но принимает литеральную строку вместо пары «строка/длина».

void  sv_catpvs(SV* sv, "literal string")
sv_catpvs_flags

Как и sv_catpvn_flags, но принимает литеральную строку вместо пары «строка/длина».

void  sv_catpvs_flags(SV* sv, "literal string", I32 flags)
sv_catpvs_mg

Как и sv_catpvn_mg, но принимает литеральную строку вместо пары «строка/длина».

void  sv_catpvs_mg(SV* sv, "literal string")
sv_catpvs_nomg

Как и sv_catpvn_nomg, но принимает литеральную строку вместо пары «строка/длина».

void  sv_catpvs_nomg(SV* sv, "literal string")
sv_catsv
sv_catsv_flags
sv_catsv_mg
sv_catsv_nomg

Эти функции конкатенируют строку из SV sstr в конец строки в SV dsv. Если sstr равно null, эти функции являются бесполезными; в противном случае изменяется только dsv.

Они отличаются только выполняемой магией:

sv_catsv_mg выполняет магию «get» для обоих SV перед копированием и магию «set» для dsv после копирования.

sv_catsv выполняет только магию «get» для обоих SV.

sv_catsv_nomg пропускает всю магию.

sv_catsv_flags имеет дополнительный параметр flags, который позволяет использовать SV_GMAGIC и/или SV_SMAGIC для указания любой комбинации обработки магии (хотя для обоих или ни одного SV будет применена магия «get»).

sv_catsv, sv_catsv_mg, и sv_catsv_nomg реализованы на основе sv_catsv_flags.

void  sv_catsv      (SV *dsv, SV *sstr)
void  sv_catsv_flags(SV * const dsv, SV * const sstr,
                     const I32 flags)
void  sv_catsv_mg   (SV *dsv, SV *sstr)
void  sv_catsv_nomg (SV *dsv, SV *sstr)
SV_CHECK_THINKFIRST

Удаляет любые ограничения из sv, которые необходимо учесть перед тем, как его можно будет изменить. Например, если используется копирование при записи (COW), сейчас самое время выполнить это копирование.

Если вам известно, что вы собираетесь изменить значение PV sv, используйте вместо этого "SV_CHECK_THINKFIRST_COW_DROP", чтобы избежать записи, которая будет немедленно перезаписана.

void  SV_CHECK_THINKFIRST(SV * sv)
SV_CHECK_THINKFIRST_COW_DROP

Вызывайте эту функцию, когда собираетесь заменить значение PV в sv, что потенциально является копированием при записи. Она прерывает любое совместное использование с другими SV, чтобы не происходило копирование при записи (COW). Это копирование было бы бесполезным, поскольку оно сразу же будет изменено на что-то другое. Эта функция также удаляет любые другие ограничения, которые могут быть проблематичными при изменении sv.

void  SV_CHECK_THINKFIRST_COW_DROP(SV * sv)
sv_chop

Эффективное удаление символов из начала буфера строки. SvPOK(sv), или по крайней мере SvPOKp(sv), должны быть истинными, и ptr должен указывать на место внутри буфера строки. ptr становится первым символом скорректированной строки. Использует хак OOK.

Результат: только SvPOK(sv) и SvPOKp(sv) среди флагов OK будут истинными.

Внимательно: после возвращения этой функции ptr и SvPVX_const(sv) могут больше не ссылаться на тот же фрагмент данных.

Невероятное сходство имени этой функции с оператором Perl chop — просто совпадение. Эта функция работает слева направо; chop работает справа налево.

void  sv_chop(SV * const sv, const char * const ptr)
sv_clear

Очистка SV: вызов любых деструкторов, освобождение используемой памяти и освобождение самого тела. Голова SV не освобождается, хотя её тип устанавливается в все единицы, чтобы случайно не предполагалось, что она активна во время глобального разрушения и т. п. Эту функцию следует вызывать только тогда, когда REFCNT равно нулю. В большинстве случаев вы захотите вызвать SvREFCNT_dec вместо этого.

void  sv_clear(SV * const orig_sv)
sv_cmp

Сравнивает строки в двух SV. Возвращает -1, 0 или 1, указывая, меньше ли строка в sv1, равна или больше строки в sv2. Поддерживает UTF-8 и 'use bytes', обрабатывает магию get и при необходимости приведёт аргументы к строкам. См. также "sv_cmp_locale".

I32  sv_cmp(SV * const sv1, SV * const sv2)
sv_cmp_flags

Сравнивает строки в двух SV. Возвращает -1, 0 или 1, указывая, меньше ли строка в sv1, равна или больше строки в sv2. Поддерживает UTF-8 и 'use bytes', и при необходимости приведёт аргументы к строкам. Если флаги содержат SV_GMAGIC, обрабатывает магию get. См. также "sv_cmp_locale_flags".

I32  sv_cmp_flags(SV * const sv1, SV * const sv2, const U32 flags)
sv_cmp_locale

Сравнивает строки в двух SV с учётом локали. Поддерживает UTF-8 и 'use bytes', обрабатывает магию get и при необходимости приведёт аргументы к строкам. См. также "sv_cmp".

I32  sv_cmp_locale(SV * const sv1, SV * const sv2)
sv_cmp_locale_flags

Сравнивает строки в двух SV с учётом локали. Поддерживает UTF-8 и 'use bytes' и при необходимости приведёт аргументы к строкам. Если флаги содержат SV_GMAGIC, обрабатывает магию get. См. также "sv_cmp_flags".

I32  sv_cmp_locale_flags(SV * const sv1, SV * const sv2,
                         const U32 flags)
sv_collxfrm

Вызывает sv_collxfrm_flags с флагом SV_GMAGIC. См. "sv_collxfrm_flags".

char *  sv_collxfrm(SV * const sv, STRLEN * const nxp)
sv_collxfrm_flags

Добавляет магию трансформации сортировки в SV, если она ещё не присутствует. Если флаги содержат SV_GMAGIC, обрабатывает магию get.

Любая переменная скалярного типа может содержать магию PERL_MAGIC_collxfrm, которая содержит данные скаляра, но преобразована в формат, позволяющий использовать обычное сравнение памяти для сравнения данных в соответствии с настройками локали.

char *  sv_collxfrm_flags(SV * const sv, STRLEN * const nxp,
                          I32 const flags)
sv_copypv
sv_copypv_flags
sv_copypv_nomg

Эти функции копируют строковое представление исходного SV в целевой SV. Автоматически выполняют преобразование числовых значений в строки. Гарантированно сохраняют флаг UTF8 даже от перегруженных объектов. Похожи по природе на sv_2pv[_flags], но работают непосредственно со SV, а не только со строкой. В основном используют "sv_2pv_flags" для выполнения работы, за исключением случаев, когда при этом теряется свойство UTF-8 PV.

Три формы различаются только тем, выполняют ли они магию «get» для sv. sv_copypv_nomg пропускает магию «get»; sv_copypv выполняет её; и sv_copypv_flags выполняет её (если бит SV_GMAGIC установлен в flags) или нет (если этот бит сброшен).

void  sv_copypv      (SV * const dsv, SV * const ssv)
void  sv_copypv_flags(SV * const dsv, SV * const ssv,
                      const I32 flags)
void  sv_copypv_nomg (SV * const dsv, SV * const ssv)
SvCUR

Возвращает длину PV внутри SV в байтах. Обратите внимание, что это может не совпадать с Perl's length; для этого используйте sv_len_utf8(sv). См. также "SvLEN".

STRLEN  SvCUR(SV* sv)
SvCUR_set

Устанавливает текущую длину C-строки в SV в байтах. См. "SvCUR" и SvIV_set.

void  SvCUR_set(SV* sv, STRLEN len)
sv_2cv

Используя различные приёмы, пытается получить CV из SV; в дополнение, если возможно, устанавливает *st и *gvp в хэш-таблицу и GV, связанные с ним. Флаги в lref передаются в gv_fetchsv.

CV *  sv_2cv(SV *sv, HV ** const st, GV ** const gvp,
             const I32 lref)
sv_dec
sv_dec_nomg

Эти функции автоматически уменьшают значение в SV, выполняя преобразование строки в число при необходимости. Обе функции обрабатывают перегрузку операторов.

Они отличаются тем, что:

sv_dec обрабатывает магию «get»; sv_dec_nomg пропускает магию «get».

void  sv_dec(SV * const sv)
sv_derived_from

Точно так же, как "sv_derived_from_pv", но не принимает параметр flags.

bool  sv_derived_from(SV *sv, const char * const name)
sv_derived_from_hv

Точно так же, как "sv_derived_from_pvn", но принимает строку с именем в качестве HvNAME заданного HV (который, вероятно, представляет собой хэш-таблицу).

bool  sv_derived_from_hv(SV *sv, HV *hv)
sv_derived_from_pv

Точно так же, как "sv_derived_from_pvn", но принимает нуль-терминированную строку вместо пары «строка/длина».

bool  sv_derived_from_pv(SV *sv, const char * const name,
                         U32 flags)
sv_derived_from_pvn

Возвращает булево значение, указывающее, происходит ли наследование от указанного класса на уровне C. Для проверки наследования на уровне Perl вызовите isa() как обычный Perl-метод.

В настоящее время единственное значимое значение для flags — SVf_UTF8.

bool  sv_derived_from_pvn(SV *sv, const char * const name,
                          const STRLEN len, U32 flags)
sv_derived_from_sv

Точно так же, как "sv_derived_from_pvn", но принимает строку с именем в виде SV вместо пары «строка/длина». Рекомендуемая форма.

bool  sv_derived_from_sv(SV *sv, SV *namesv, U32 flags)
END_OF_DOCUMENT_MARKER
sv_does

Подобно "sv_does_pv", но не принимает параметр flags. 

bool  sv_does(SV *sv, const char * const name)
sv_does_pv

Подобно "sv_does_sv", но принимает строку с нулевым завершением вместо SV.

bool  sv_does_pv(SV *sv, const char * const name, U32 flags)
sv_does_pvn

Подобно "sv_does_sv", но принимает пару "строка/длина" вместо SV.

bool  sv_does_pvn(SV *sv, const char * const name,
                  const STRLEN len, U32 flags)
sv_does_sv

Возвращает логическое значение, указывающее, выполняет ли SV определённую, именованную роль. SV может быть объектом Perl или именем класса Perl.

bool  sv_does_sv(SV *sv, SV *namesv, U32 flags)
SvEND

Возвращает указатель на позицию сразу после последнего символа в строке SV, где обычно находится конечный NUL символ (даже если перловые скаляры его строго не требуют). См. "SvCUR". Доступ к символу как *(SvEND(sv)).

Предупреждение: Если SvCUR равно SvLEN, то SvEND указывает на незарезервированную память.

char*  SvEND(SV* sv)
sv_eq

Возвращает логическое значение, указывающее, идентичны ли строки в двух SV. Поддерживает UTF-8 и 'use bytes', обрабатывает магию получения и при необходимости приведёт аргументы к строкам.

Эта функция не обрабатывает перегрузку операторов. Для версии, которая обрабатывает, см. вместо этого sv_streq.

I32  sv_eq(SV *sv1, SV *sv2)
sv_eq_flags

Возвращает логическое значение, указывающее, идентичны ли строки в двух SV. Поддерживает UTF-8 и 'use bytes', а также при необходимости приведёт аргументы к строкам. Если в флагах установлен бит SV_GMAGIC, то обрабатывается и магия получения.

Эта функция не обрабатывает перегрузку операторов. Для версии, которая обрабатывает, см. вместо этого sv_streq_flags.

I32  sv_eq_flags(SV *sv1, SV *sv2, const U32 flags)
sv_force_normal

Отменяет различные типы имитации для SV: если PV — это общая строка, создаёт частную копию; если мы являемся ссылкой, прекращаем ссылаться; если мы — шаблон, понижаем до xpvmg. См. также "sv_force_normal_flags".

void  sv_force_normal(SV *sv)
sv_force_normal_flags

Отменяет различные типы имитации для SV, где имитация означает «больше, чем» строка: если PV — общая строка, делает частную копию; если мы являемся ссылкой, прекращаем ссылаться; если мы — шаблон, понижаем до xpvmg; если мы — скаляр с копированием при записи, это время записи, когда мы делаем копию, а также используется локально; если это v-строка, удаляет магию v-строки. Если установлен SV_COW_DROP_PV, тогда скаляр с копированием при записи отбрасывает буфер PV (если есть) и становится SvPOK_off, а не создаёт копию. (Используется, когда этот скаляр должен быть установлен на какое-то другое значение.) Кроме того, параметр flags передаётся в sv_unref_flags() при отмене ссылки. sv_force_normal вызывает эту функцию с флагами, установленными в 0.

Ожидается, что эта функция будет использоваться для сигнализации Perl о том, что этот SV собирается быть записанным, и что любые дополнительные учётные записи должны быть учтены. Следовательно, она вызывает ошибку для значений только для чтения.

void  sv_force_normal_flags(SV * const sv, const U32 flags)
sv_free

Уменьшает счётчик ссылок SV, и если он уменьшится до нуля, вызывает sv_clear, чтобы вызвать деструкторы и освободить всю память, используемую телом; наконец, освобождает сам заголовок SV. Обычно вызывается через макрос-обёртку SvREFCNT_dec.

void  sv_free(SV * const sv)
SvGAMAGIC

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

U32  SvGAMAGIC(SV* sv)
sv_get_backrefs

ПРИМЕЧАНИЕ: sv_get_backrefs является экспериментальным и может измениться или быть удалено без предварительного уведомления.

Если sv является целью слабого указателя, то возвращает структуру обратных ссылок, связанную со sv; в противном случае возвращает NULL.

При возвращении ненулевого результата тип возвращаемого значения имеет значение. Если это массив AV, элементы AV — слабые указатели RV, которые указывают на этот элемент. Если это любой другой тип, то сам элемент является слабой ссылкой.

См. также Perl_sv_add_backref(), Perl_sv_del_backref(), Perl_sv_kill_backrefs()

SV *  sv_get_backrefs(SV * const sv)
SvGETMAGIC

Вызывает "mg_get" для SV, если у него есть магия «получения». Например, это вызовет FETCH для привязанной переменной. Начиная с 5.37.1, эта функция гарантированно вычисляет свой аргумент ровно один раз.

void  SvGETMAGIC(SV *sv)
sv_gets

Получить строку из файла и поместить её в SV, необязательно добавляя к текущей строке. Если append не равно 0, строка добавляется к SV, а не перезаписывает его. append должен быть установлен на байтовый смещение, с которого должна начинаться добавленная строка в SV (обычно SvCUR(sv) является подходящим выбором).

char *  sv_gets(SV * const sv, PerlIO * const fp, I32 append)
SvGROW

Расширяет буфер символов в SV, чтобы в нём было место для указанного количества байтов (не забудьте зарезервировать место для дополнительного конечного NUL символа). Вызывает sv_grow для выполнения расширения при необходимости. Возвращает указатель на буфер символов. SV должен быть типа >= SVt_PV. Альтернативный вариант — вызвать sv_grow, если тип SV неизвестен.

Вы можете ошибочно предположить, что len — это количество байтов, которые нужно добавить к существующему размеру, но вместо этого это общий размер, который sv должен иметь.

char *  SvGROW(SV* sv, STRLEN len)
SvIandPOK

Возвращает булево значение, указывающее, является ли SV одновременно SvPOK() и SvIOK(). Эквивалентно SvIOK(sv) && SvPOK(sv), но более эффективно.

U32  SvIandPOK(SV* sv)
SvIandPOK_off

Снимает статус PV и IV SV в одной операции. Эквивалентно SvIOK_off(sv); SvPK_off(v);, но более эффективно.

void  SvIandPOK_off(SV* sv)
SvIandPOK_on

Указывает SV, что он является строкой и числом в одной операции. Эквивалентно SvIOK_on(sv); SvPOK_on(sv);, но более эффективно.

void  SvIandPOK_on(SV* sv)
sv_inc
sv_inc_nomg

Эти функции автоматически увеличивают значение в SV, выполняя преобразование строки в число при необходимости. Обе функции обрабатывают перегрузку операторов.

Они отличаются только тем, что sv_inc выполняет магию «получения»; sv_inc_nomg пропускает любую магию.

void  sv_inc(SV * const sv)
sv_insert

Вставляет и/или заменяет строку по указанному смещению/длине в SV. Аналогично функции Perl substr(), где littlelen байт, начиная с little, заменяют len байт строки в bigstr, начиная с offset. Обрабатывает магию получения.

void  sv_insert(SV * const bigstr, const STRLEN offset,
                const STRLEN len, const char * const little,
                const STRLEN littlelen)
sv_insert_flags

То же самое, что и sv_insert, но дополнительные flags передаются функции SvPV_force_flags, которая применяется к bigstr.

void  sv_insert_flags(SV * const bigstr, const STRLEN offset,
                      const STRLEN len, const char *little,
                      const STRLEN littlelen, const U32 flags)
sv_2io

Используя различные методы, попробуйте получить IO из SV: слот IO, если это GV; рекурсивный результат, если это RV; или слот IO символа, названного по PV, если это строка.

Магия «получения» игнорируется для переданного sv, но будет вызвана для SvRV(sv), если sv является RV.

IO *  sv_2io(SV * const sv)
SvIOK

Возвращает значение U32, указывающее, содержит ли SV целое число.

U32  SvIOK(SV* sv)
SvIOK_notUV

Возвращает логическое значение, указывающее, содержит ли SV целое число со знаком.

bool  SvIOK_notUV(SV* sv)
SvIOK_off

Снимает статус IV SV.

void  SvIOK_off(SV* sv)
SvIOK_on

Указывает SV, что это целое число.

void  SvIOK_on(SV* sv)
SvIOK_only

Указывает SV, что это целое число и отключает все остальные OK биты.

void  SvIOK_only(SV* sv)
SvIOK_only_UV

Указывает SV, что это целое без знака, и отключает все остальные OK биты.

void  SvIOK_only_UV(SV* sv)
SvIOKp

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

U32  SvIOKp(SV* sv)
SvIOK_UV

Возвращает логическое значение, указывающее, содержит ли SV целое число, которое должно интерпретироваться как без знака. Целое неотрицательное число, значение которого находится в диапазоне как IV, так и UV, может быть помечено как SvUOK или SvIOK.

bool  SvIOK_UV(SV* sv)
sv_isa

Возвращает логическое значение, указывающее, благословлён ли SV в указанный класс.

Это не проверяет подтипы или перегрузку методов. Используйте sv_isa_sv для проверки отношения наследования так же, как оператор isa, учитывая перегрузку методов isa(); или sv_derived_from_sv для непосредственной проверки фактического типа объекта.

int  sv_isa(SV *sv, const char * const name)
sv_isa_sv

ПРИМЕЧАНИЕ: sv_isa_sv является экспериментальным и может измениться или быть удалено без предварительного уведомления.

Возвращает логическое значение, указывающее, является ли SV объектной ссылкой и происходит ли она от указанного класса, учитывая любую перегрузку метода isa(), которая у неё может быть. Возвращает false, если sv не является ссылкой на объект или не происходит от указанного класса.

Это функция, используемая для реализации поведения оператора isa.

Не вызывает магию для sv.

Не следует путать с более старой функцией sv_isa, которая не использует перегруженный метод isa(), а также не проверяет подклассы.

bool  sv_isa_sv(SV *sv, SV *namesv)
SvIsBOOL

Возвращает true, если SV является одним из специальных булевых констант (PL_sv_yes или PL_sv_no) или является обычным SV, последнее присвоение которого сохранило копию одного из них.

bool  SvIsBOOL(SV* sv)
SvIsCOW

Возвращает значение U32, указывающее, является ли SV копируемым по требованию (либо общие скаляры хеша ключей, либо полные скаляры Copy On Write, если для COW настроена версия 5.9.0).

U32  SvIsCOW(SV* sv)
SvIsCOW_shared_hash

Возвращает булево значение, указывающее, является ли SV скаляром общего хеша ключей, копируемым по требованию.

bool  SvIsCOW_shared_hash(SV* sv)
sv_isobject

Возвращает булево значение, указывающее, является ли SV RV, указывающим на благословенный объект. Если SV не является RV или объект не благословен, возвращается false.

int  sv_isobject(SV *sv)
SvIV
SvIV_nomg
SvIVx

Каждый из них преобразует данный SV в IV и возвращает его. Возвращаемое значение во многих случаях будет сохранено в слоте IV sv, но не во всех. (Используйте "sv_setiv", чтобы убедиться, что это так).

Начиная с версии 5.37.1, все гарантированно оценивают sv только один раз.

SvIVx теперь идентичен SvIV, но до версии 5.37.1 только он гарантировал оценку sv только один раз.

SvIV_nomg аналогичен SvIV, но не выполняет магию 'get'.

IV  SvIV(SV *sv)
sv_2iv_flags

Возвращает целое значение SV, выполняя необходимые преобразования из строки. Если у flags установлен бит SV_GMAGIC, выполняется mg_get() предварительно. Обычно используется через макросы SvIV(sv) и SvIVx(sv). 

IV  sv_2iv_flags(SV * const sv, const I32 flags)
SvIV_set

Устанавливает значение указателя IV в sv в val. Возможно выполнить ту же функцию с помощью присваивания lvalue к SvIVX. Однако в будущих версиях Perl будет более эффективным использовать SvIV_set вместо lvalue-присваивания к SvIVX. 

void  SvIV_set(SV* sv, IV val)
SvIVX

Возвращает исходное значение в слоте IV SV без проверок или преобразований. Используйте только когда уверены, что SvIOK истинно. См. также "SvIV".

IV  SvIVX(SV* sv)
SvLEN

Возвращает размер буфера строки в SV, не включая часть, приписываемую SvOOK. См. "SvCUR".

STRLEN  SvLEN(SV* sv)
sv_len

Возвращает длину строки в SV. Обрабатывает магию и преобразование типов и соответствующим образом устанавливает флаг UTF8. См. также "SvCUR", который предоставляет прямой доступ к слоту xpv_cur.

STRLEN  sv_len(SV * const sv)
SvLEN_set

Устанавливает размер буфера строки для SV. См. "SvLEN".

void  SvLEN_set(SV* sv, STRLEN len)
sv_len_utf8
sv_len_utf8_nomg

Эти функции возвращают количество символов в строке SV, считая широкие байты UTF-8 за один символ. Обе обрабатывают преобразование типов. Разница только в том, что sv_len_utf8 выполняет магию 'get', а sv_len_utf8_nomg пропускает любую магию.

STRLEN  sv_len_utf8(SV * const sv)
SvLOCK

Организует получение блокировки взаимного исключения на sv, если соответствующий модуль загружен.

void  SvLOCK(SV* sv)
sv_magic

Добавляет магию к SV. Сначала повышает sv до типа SVt_PVMG при необходимости, затем добавляет новый элемент магии типа how в начало списка магии.

См. "sv_magicext" (которое sv_magic теперь вызывает) для описания обработки аргументов name и namlen.

Для добавления магии к SvREADONLY SV и для добавления более одного экземпляра той же how необходимо использовать sv_magicext.

void  sv_magic(SV * const sv, SV * const obj, const int how,
               const char * const name, const I32 namlen)
sv_magicext

Добавляет магию к SV, повышая его тип при необходимости. Применяет предоставленный vtable и возвращает указатель на добавленную магию.

Обратите внимание, что sv_magicext позволит то, что sv_magic не позволит. В частности, вы можете добавить магию к SvREADONLY SV и добавить более одного экземпляра той же how.

Если namlen больше нуля, то выполняется копирование name, если namlen равно нулю, то name сохраняется как есть, и - как ещё один особый случай - если (name && namlen == HEf_SVKEY) равно true, то name предполагается содержать SV* и сохраняется как есть с увеличенным REFCNT.

(Это теперь используется как подпрограмма sv_magic.)

MAGIC *  sv_magicext(SV * const sv, SV * const obj, const int how,
                     const MGVTBL * const vtbl,
                     const char * const name, const I32 namlen)
SvMAGIC_set

Устанавливает значение указателя MAGIC в sv на val. См. "SvIV_set".

void  SvMAGIC_set(SV* sv, MAGIC* val)
sv_2mortal

Помечает существующий SV как смертный. SV будет уничтожен "вскоре", либо явным вызовом FREETMPS, либо неявным вызовом в точках, таких как границы операторов. Включен SvTEMP(), что означает, что буфер строки SV может быть "украден", если этот SV скопирован. См. также "sv_newmortal" и "sv_mortalcopy".

SV *  sv_2mortal(SV * const sv)
sv_mortalcopy

Создаёт новый SV, который является копией исходного SV (используя sv_setsv). Новый SV помечен как смертный. Он будет уничтожен "вскоре", либо явным вызовом FREETMPS, либо неявным вызовом в точках, таких как границы операторов. См. также "sv_newmortal" и "sv_2mortal".

SV *  sv_mortalcopy(SV * const oldsv)
sv_mortalcopy_flags

Как sv_mortalcopy, но дополнительные flags передаются в sv_setsv_flags.

SV *  sv_mortalcopy_flags(SV * const oldsv, U32 flags)
sv_newmortal

Создаёт новый нулевой SV, который является смертным. Счётчик ссылок SV установлен в 1. Он будет уничтожен "вскоре", либо явным вызовом FREETMPS, либо неявным вызовом в точках, таких как границы операторов. См. также "sv_mortalcopy" и "sv_2mortal".

SV *  sv_newmortal()
SvNIOK

Возвращает значение U32, указывающее, содержит ли SV число, целое число или двойное значение.

U32  SvNIOK(SV* sv)
SvNIOK_off

Сбрасывает статус NV/IV SV.

void  SvNIOK_off(SV* sv)
SvNIOKp

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

U32  SvNIOKp(SV* sv)
SvNOK

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

U32  SvNOK(SV* sv)
SvNOK_off

Сбрасывает статус NV SV.

void  SvNOK_off(SV* sv)
SvNOK_on

Указывает SV, что это двойное значение.

void  SvNOK_on(SV* sv)
SvNOK_only

Указывает SV, что это двойное значение, и отключает все остальные биты OK.

void  SvNOK_only(SV* sv)
SvNOKp

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

U32  SvNOKp(SV* sv)
sv_nolocking

DEPRECATED! Планируется удалить sv_nolocking из будущих релизов Perl. Не используйте в новом коде; удалите из существующего.

Псевдофункция, которая "блокирует" SV, когда модуль блокировки отсутствует. Существует для избегания проверки на указатель функции NULL и потому что она может предупреждать при определённом уровне строгости.

"Заменена" на sv_nosharing().

void  sv_nolocking(SV *sv)
sv_nounlocking

DEPRECATED! Планируется удалить sv_nounlocking из будущих релизов Perl. Не используйте в новом коде; удалите из существующего.

Псевдофункция, которая "разблокирует" SV, когда модуль блокировки отсутствует. Существует для избегания проверки на указатель функции NULL и потому что она может предупреждать при определённом уровне строгости.

"Заменена" на sv_nosharing().

void  sv_nounlocking(SV *sv)
sv_numeq

Удобный ярлык для вызова sv_numeq_flags с флагом SV_GMAGIC. Эта функция в основном ведёт себя как Perl-код $sv1 == $sv2.

bool  sv_numeq(SV *sv1, SV *sv2)
sv_numeq_flags

Возвращает булево значение, указывающее, являются ли числа в двух SV идентичными. Если у аргумента flags установлен бит SV_GMAGIC, он также обрабатывает магию get. Преобразует аргументы в числа при необходимости. Обрабатывает NULL как undef.

Если у flags не установлен бит SV_SKIP_OVERLOAD, будет сделана попытка использовать перегрузку ==. Если такая перегрузка не существует или флаг установлен, вместо этого будет использовано обычное численное сравнение.

bool  sv_numeq_flags(SV *sv1, SV *sv2, const U32 flags)
SvNV
SvNV_nomg
SvNVx

Каждый из них преобразует данный SV в NV и возвращает его. Возвращаемое значение во многих случаях будет сохранено в слоте NV sv, но не во всех. (Используйте "sv_setnv", чтобы убедиться, что это так).

Начиная с версии 5.37.1, все гарантированно оценивают sv только один раз.

SvNVx теперь идентичен SvNV, но до версии 5.37.1 только он гарантировал оценку sv только один раз.

SvNV_nomg аналогичен SvNV, но не выполняет магию 'get'.

NV  SvNV(SV *sv)
sv_2nv_flags

Возвращает числовое значение SV, выполняя необходимые преобразования из строки или целого числа. Если у flags установлен бит SV_GMAGIC, выполняется mg_get() предварительно. Обычно используется через макросы SvNV(sv) и SvNVx(sv).

NV  sv_2nv_flags(SV * const sv, const I32 flags)
SvNV_set

Устанавливает значение указателя NV в sv на val. См. "SvIV_set".

void  SvNV_set(SV* sv, NV val)
SvNVX

Возвращает исходное значение в слоте NV SV без проверок или преобразований. Используйте только когда уверены, что SvNOK истинно. См. также "SvNV".

NV  SvNVX(SV* sv)
SvOK

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

U32  SvOK(SV* sv)
SvOOK

Возвращает U32, указывающее, смещен ли указатель на буфер строки. Этот трюк используется внутри для ускорения удаления символов из начала "SvPV". Когда SvOOK равно true, начало выделенного буфера строки фактически находится на SvOOK_offset() байтах перед SvPVX. Этот смещение раньше хранилось в SvIVX, но теперь хранится в резервном разделе буфера.

U32  SvOOK(SV* sv)
SvOOK_off

Удаляет любой смещение строки.

void  SvOOK_off(SV * sv)
SvOOK_offset

Считывает в len смещение от SvPVX назад к истинному началу выделенного буфера, которое будет ненулевым, если sv_chop использовалось для эффективного удаления символов из начала буфера. Реализовано как макрос, принимающий адрес len, который должен быть типа STRLEN. Вычисляет sv более одного раза. Устанавливает len в 0, если SvOOK(sv) ложно.

void  SvOOK_offset(SV*sv, STRLEN len)
SvPOK

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

U32  SvPOK(SV* sv)
SvPOK_off

Сбрасывает состояние PV SV.

void  SvPOK_off(SV* sv)
SvPOK_on

Указывает SV, что это строка.

void  SvPOK_on(SV* sv)
SvPOK_only

Указывает SV, что это строка, и отключает все остальные OK биты. Также отключит статус UTF-8.

void  SvPOK_only(SV* sv)
SvPOK_only_UTF8

Указывает SV, что это строка и отключает все остальные OK биты, и оставляет статус UTF-8 таким, каким он был.

void  SvPOK_only_UTF8(SV* sv)
SvPOKp

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

U32  SvPOKp(SV* sv)
sv_pos_b2u

Преобразует значение, на которое указывает offsetp, из количества байтов от начала строки в количество эквивалентных символов UTF-8. Обрабатывает магию и приведение типов.

Используйте sv_pos_b2u_flags вместо этого, которое правильно обрабатывает строки длиной более 2 Гб.

void  sv_pos_b2u(SV * const sv, I32 * const offsetp)
sv_pos_b2u_flags

Преобразует offset из количества байтов от начала строки в количество эквивалентных символов UTF-8. Обрабатывает приведение типов. flags передается в SvPV_flags, и обычно должен быть SV_GMAGIC|SV_CONST_RETURN, чтобы обработать магию.

STRLEN  sv_pos_b2u_flags(SV * const sv, STRLEN const offset,
                         U32 flags)
sv_pos_u2b

Преобразует значение, на которое указывает offsetp, из количества символов UTF-8 от начала строки в количество эквивалентных байтов; если lenp ненулевое, выполняет то же самое для lenp, но на этот раз начиная со смещения, а не с начала строки. Обрабатывает магию и приведение типов.

Используйте sv_pos_u2b_flags вместо этого, которое правильно обрабатывает строки длиной более 2 Гб.

void  sv_pos_u2b(SV * const sv, I32 * const offsetp,
                 I32 * const lenp)
sv_pos_u2b_flags

Преобразует смещение из количества символов UTF-8 от начала строки в количество эквивалентных байтов; если lenp ненулевое, выполняет то же самое для lenp, но на этот раз начиная со offset, а не с начала строки. Обрабатывает приведение типов. flags передается в SvPV_flags, и обычно должен быть SV_GMAGIC|SV_CONST_RETURN, чтобы обработать магию.

STRLEN  sv_pos_u2b_flags(SV * const sv, STRLEN uoffset,
                         STRLEN * const lenp, U32 flags)
SvPV
SvPV_const
SvPV_flags
SvPV_flags_const
SvPV_flags_mutable
SvPV_mutable
SvPV_nolen
SvPV_nolen_const
SvPV_nomg
SvPV_nomg_const
SvPV_nomg_const_nolen
SvPV_nomg_nolen
SvPVbyte
SvPVbyte_nolen
SvPVbyte_nomg
SvPVbyte_or_null
SvPVbyte_or_null_nomg
SvPVbytex
SvPVbytex_nolen
SvPVutf8
SvPVutf8_nolen
SvPVutf8_nomg
SvPVutf8_or_null
SvPVutf8_or_null_nomg
SvPVutf8x
SvPVx
SvPVx_const
SvPVx_nolen
SvPVx_nolen_const

Каждая из них возвращает указатель на строку в SvOOK, или строковое представление "SvPV", если она не содержит строку. SV может кэшировать строковое представление, становясь SvOOK.

Это очень простая и распространенная операция, поэтому существует много слегка отличающихся версий.

Обратите внимание, что нет гарантии, что возвращаемое значение SvOOK_offset(), например, равно SvPVX, или что SvIVX содержит действительные данные, или что последовательные вызовы 

U32  SvOOK(SV* sv)
(или другой из этих форм) будут каждый раз возвращать одно и то же значение указателя. Это связано с тем, как обрабатываются такие вещи, как перегрузка и Copy-On-Write. В этих случаях возвращаемое значение может указывать на временный буфер или что-то подобное. Если вам абсолютно необходимо, чтобы поле SvPVX было допустимым (например, если вы собираетесь его изменить), см. "SvPV_force".

Отличия между формами:

Формы без byte и utf8 в своих названиях (например, SvPV или SvPV_nolen) могут раскрывать внутренний буфер строк SV. Если этот буфер состоит целиком из байтов от 0 до 255 и включает байты выше 127, вы ОБЯЗАНЫ обратиться к SvUTF8, чтобы определить фактические кодовые точки, которые должна содержать строка. Как правило, лучше предпочесть SvPVbyte, SvPVutf8 и т. п. Для получения более подробной информации см. "Как передать Perl-строку в библиотеку C?" в perlguts.

Формы с flags в своих названиях позволяют использовать параметр flags для указания обработки магической операции 'get' (установив флаг SV_GMAGIC) или пропуска 'get' магии (сбросив его). Другие формы обрабатывают 'get' магию, за исключением форм с nomg в своих названиях, которые пропускают 'get' магию.

Формы, принимающие параметр len, установят эту переменную в длину результатной строки в байтах (это макросы, поэтому не используйте &len).

Формы с nolen в своих названиях указывают, что у них нет параметра len. Их следует использовать только в том случае, если известно, что PV является строкой C, завершающейся байтом NUL и без промежуточных байтов NUL; или когда вам не нужно знать ее длину.

Формы с const в своих названиях возвращают const char *, чтобы компилятор, вероятно, жаловался, если вы попытаетесь изменить содержимое строки (если вы сами не отбросите const).

Другие формы возвращают изменяемый указатель, чтобы строка была изменяемой для вызывающей стороны; это подчеркивается для форм с mutable в своих названиях.

Начиная с 5.38, все формы гарантированно оценивают sv ровно один раз. Для более ранних версий Perl используйте форму, название которой заканчивается на x для однократной оценки.

SvPVutf8 подобно SvPV, но преобразует sv в UTF-8, если это еще не UTF-8. Аналогично, другие формы с utf8 в своих названиях соответствуют соответствующим формам без них.

SvPVutf8_or_null и SvPVutf8_or_null_nomg не имеют соответствующих форм без utf8. Вместо этого они подобны SvPVutf8_nomg, но когда sv не определено, они возвращают NULL.

SvPVbyte подобно SvPV, но преобразует sv в байтовое представление сначала, если оно закодировано как UTF-8. Если sv не может быть понижен до UTF-8, он генерирует ошибку. Аналогично, другие формы с byte в своих названиях соответствуют соответствующим формам без них.

SvPVbyte_or_null не имеет соответствующей формы без byte. Вместо этого она подобна SvPVbyte, но когда sv не определено, она возвращает NULL. 

char*        SvPV                 (SV* sv, STRLEN len)
const char*  SvPV_const           (SV* sv, STRLEN len)
char*        SvPV_flags           (SV* sv, STRLEN len, U32 flags)
const char*  SvPV_flags_const     (SV* sv, STRLEN len, U32 flags)
char*        SvPV_flags_mutable   (SV* sv, STRLEN len, U32 flags)
char*        SvPV_mutable         (SV* sv, STRLEN len)
char*        SvPV_nolen           (SV* sv)
const char*  SvPV_nolen_const     (SV* sv)
char*        SvPV_nomg            (SV* sv, STRLEN len)
const char*  SvPV_nomg_const      (SV* sv, STRLEN len)
const char*  SvPV_nomg_const_nolen(SV* sv)
char*        SvPV_nomg_nolen      (SV* sv)
char*        SvPVbyte             (SV* sv, STRLEN len)
char*        SvPVbyte_nolen       (SV* sv)
char*        SvPVbyte_nomg        (SV* sv, STRLEN len)
char*        SvPVbyte_or_null     (SV* sv, STRLEN len)
char*        SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
char*        SvPVbytex            (SV* sv, STRLEN len)
char*        SvPVbytex_nolen      (SV* sv)
char*        SvPVutf8             (SV* sv, STRLEN len)
char*        SvPVutf8_nolen       (SV* sv)
char*        SvPVutf8_nomg        (SV* sv, STRLEN len)
char*        SvPVutf8_or_null     (SV* sv, STRLEN len)
char*        SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
char*        SvPVutf8x            (SV* sv, STRLEN len)
char*        SvPVx                (SV* sv, STRLEN len)
const char*  SvPVx_const          (SV* sv, STRLEN len)
char*        SvPVx_nolen          (SV* sv)
const char*  SvPVx_nolen_const    (SV* sv)
sv_2pv
sv_2pv_flags

Эти реализации различных форм макросов "SvPV" в perlapi. Макросы являются предпочтительным интерфейсом.

Эти макросы возвращают указатель на значение строки SV (преобразуя его в строку, если необходимо) и устанавливают *lp в его длину в байтах.

Формы отличаются тем, что обычный sv_2pvbyte всегда обрабатывает 'get' магию; и sv_2pvbyte_flags обрабатывает 'get' магию только в том случае, если flags содержит SV_GMAGIC.

char *  sv_2pv      (SV *sv, STRLEN *lp)
char *  sv_2pv_flags(SV * const sv, STRLEN * const lp,
                     const U32 flags)
sv_2pvbyte
sv_2pvbyte_flags

Эти реализации различных форм макросов "SvPVbyte" в perlapi. Макросы являются предпочтительным интерфейсом.

Эти макросы возвращают указатель на байтовое представление SV и устанавливают *lp в его длину. Если SV помечен как закодированный в UTF-8, он будет, если возможно, преобразован в строку байтов. Если SV не может быть преобразован, они генерируют ошибку.

Формы отличаются тем, что обычный sv_2pvbyte всегда обрабатывает 'get' магию; и sv_2pvbyte_flags обрабатывает 'get' магию только в том случае, если flags содержит SV_GMAGIC.

char *  sv_2pvbyte      (SV *sv, STRLEN * const lp)
char *  sv_2pvbyte_flags(SV *sv, STRLEN * const lp,
                         const U32 flags)
SvPVCLEAR

Обеспечивает, что sv является SVt_PV, что его SvCUR равен 0 и что он правильно завершается нулем. Эквивалентно sv_setpvs(""), но более эффективно.

char *  SvPVCLEAR(SV* sv)
SvPVCLEAR_FRESH

Подобно SvPVCLEAR, но оптимизирован для недавно созданных SVt_PV/PVIV/PVNV/PVMG, которые уже имеют выделенный буфер PV, но не имеют SvTHINKFIRST.

char *  SvPVCLEAR_FRESH(SV* sv)
SvPV_force
SvPV_force_flags
SvPV_force_flags_mutable
SvPV_force_flags_nolen
SvPV_force_mutable
SvPV_force_nolen
SvPV_force_nomg
SvPV_force_nomg_nolen
SvPVbyte_force
SvPVbytex_force
SvPVutf8_force
SvPVutf8x_force
SvPVx_force

Эти функции похожи на "SvPV", возвращая строку из SV, но будут принудительно превращать SV в строку ("SvPOK"), и только в строку ("SvPOK_only"), любыми способами. Вам необходимо использовать одну из этих force функций, если вы собираетесь обновить "SvPVX" напрямую.

Обратите внимание, что принудительное преобразование произвольного скаляра в обычный PV может потенциально удалить полезные данные из него. Например, если SV был SvROK, то ссылка будет иметь декрементированный счётчик ссылок, а сам SV может быть преобразован в SvPOK скаляр со строковым буфером, содержащим значение, например, "ARRAY(0x1234)".

Различия между формами:

Формы с flags в их именах позволяют использовать параметр flags для указания выполнения магической операции "get" (установкой флага SV_GMAGIC) или пропуская магическую операцию "get" (сбросом флага). Другие формы выполняют магическую операцию "get", за исключением форм с nomg в их именах, которые пропускают магическую операцию "get".

Формы, принимающие параметр len, установят эту переменную в значение байтовой длины результирующей строки (это макросы, поэтому не используйте &len).

Формы с nolen в их именах указывают на отсутствие параметра len. Их следует использовать только тогда, когда известно, что PV является строкой C, завершенной байтом NUL и без промежуточных байтов NUL; или когда вас не интересует её длина.

Формы с mutable в их именах по сути идентичны формам без них, но имя подчеркивает, что строка может быть изменена вызывающим кодом, что верно для всех форм.

SvPVutf8_force аналогична SvPV_force, но конвертирует sv в UTF-8, если это не UTF-8.

SvPVutf8x_force аналогична SvPVutf8_force, но гарантирует, что sv будет вычислено только один раз; используйте более эффективную SvPVutf8_force в противном случае.

SvPVbyte_force аналогична SvPV_force, но конвертирует sv в байтовую форму, если она закодирована в UTF-8. Если SV не может быть понижен с UTF-8, произойдёт ошибка.

SvPVbytex_force аналогична SvPVbyte_force, но гарантирует, что sv будет вычислено только один раз; используйте более эффективную SvPVbyte_force в противном случае.

char*  SvPV_force              (SV* sv, STRLEN len)
char*  SvPV_force_flags        (SV * sv, STRLEN len, U32 flags)
char*  SvPV_force_flags_mutable(SV * sv, STRLEN len, U32 flags)
char*  SvPV_force_flags_nolen  (SV * sv, U32 flags)
char*  SvPV_force_mutable      (SV * sv, STRLEN len)
char*  SvPV_force_nolen        (SV* sv)
char*  SvPV_force_nomg         (SV* sv, STRLEN len)
char*  SvPV_force_nomg_nolen   (SV * sv)
char*  SvPVbyte_force          (SV * sv, STRLEN len)
char*  SvPVbytex_force         (SV * sv, STRLEN len)
char*  SvPVutf8_force          (SV * sv, STRLEN len)
char*  SvPVutf8x_force         (SV * sv, STRLEN len)
char*  SvPVx_force             (SV* sv, STRLEN len)
SvPV_free

Освобождает буфер PV в sv, оставляя ситуацию в неопределённом состоянии, поэтому следует использовать только как часть более крупной операции

void  SvPV_free(SV * sv)
sv_pvn_force_flags

Получает строку из SV каким-то разумным способом. Если flags содержит бит SV_GMAGIC, произведёт "mg_get" на sv при необходимости, иначе — нет. sv_pvn_force и sv_pvn_force_nomg реализованы через эту функцию. Обычно вам нужно использовать различные обертки-макросы: см. "SvPV_force" и "SvPV_force_nomg". 

char *  sv_pvn_force_flags(SV * const sv, STRLEN * const lp,
                           const U32 flags)
SvPV_renew

Микрооптимизация низкого уровня "SvGROW". В целом лучше использовать SvGROW вместо этого. Это потому, что SvPV_renew игнорирует потенциальные проблемы, с которыми справляется SvGROW. sv должен иметь настоящий PV, не связанный с такими вещами, как COW. Использование SV_CHECK_THINKFIRST или SV_CHECK_THINKFIRST_COW_DROP перед вызовом этой функции должно исправить ситуацию, но почему бы просто не использовать SvGROW, если вы не уверены в происхождении?

void  SvPV_renew(SV* sv, STRLEN len)
SvPV_set

Вероятно, это не то, что вам нужно, вам скорее нужны "sv_usepvn_flags" или "sv_setpvn" или "sv_setpvs".

Устанавливает значение указателя PV в sv на выделенную Perl-строку, завершающуюся NUL, val. Также см. "SvIV_set".

Не забудьте освободить предыдущий буфер PV. Есть много вещей, которые нужно проверить. Будьте осторожны, так как существующий указатель может быть вовлечён в copy-on-write или другие операции, поэтому выполните SvOOK_off(sv) и используйте sv_force_normal или SvPV_force (или проверьте флаг SvIsCOW) прежде, чем убедиться в безопасности этого изменения. Затем, если это не COW, вызовите "SvPV_free" для освобождения предыдущего буфера PV.

void  SvPV_set(SV* sv, char* val)
SvPV_shrink_to_cur

Уменьшает любой неиспользуемый хвост памяти в PV объекта sv, который должен иметь реальный PV без свойств COW. Подумайте, прежде чем использовать эту функцию. Стоит ли отказ от COW экономия места? Останется ли необходимый размер sv прежним?

Если ответы оба да, то используйте "SV_CHECK_THINKFIRST" или "SV_CHECK_THINKFIRST_COW_DROP" перед вызовом этой функции.

void  SvPV_shrink_to_cur(SV* sv)
sv_2pvutf8
sv_2pvutf8_flags

Эти функции реализуют различные формы макроса "SvPVutf8" в perlapi. Макросы — предпочтительный интерфейс.

Они возвращают указатель на UTF-8-представление SV и устанавливают *lp в его длину в байтах. В качестве побочного эффекта они могут привести к преобразованию SV в UTF-8.

Различия заключаются в том, что обычный sv_2pvutf8 всегда обрабатывает магическую операцию "get", а sv_2pvutf8_flags обрабатывает "get" магию только тогда, когда flags содержит SV_GMAGIC. 

char *  sv_2pvutf8      (SV *sv, STRLEN * const lp)
char *  sv_2pvutf8_flags(SV *sv, STRLEN * const lp,
                         const U32 flags)
SvPVX
SvPVX_const
SvPVX_mutable
SvPVXx

Эти функции возвращают указатель на физическую строку в SV. SV должен содержать строку. До версии 5.9.3 использование этих функций небезопасно, если тип SV >= SVt_PV.

Также они используются для хранения имени автоматически загружаемой подпрограммы в XS AUTOLOAD-процедуре. См. "Автозагрузка с XSUB" в perlguts.

SvPVXx идентична SvPVX.

SvPVX_mutable — просто синоним SvPVX, но её имя подчеркивает, что строка может быть изменена вызывающим кодом.

SvPVX_const отличается тем, что возвращаемое значение было приведено так, что компилятор выдаст ошибку, если вы попытаетесь изменить содержимое строки (если вы не приведёте её тип самостоятельно).

char*        SvPVX        (SV* sv)
const char*  SvPVX_const  (SV* sv)
char*        SvPVX_mutable(SV* sv)
char*        SvPVXx       (SV* sv)
SvPVXtrue

Возвращает булево значение о том, содержит ли sv PV, который считается истинным. FALSE возвращается, если sv не содержит PV, или если PV нулевой длины, или состоит только из символа '0'. Все остальные значения PV считаются истинными.

Начиная с Perl v5.37.1, sv вычисляется ровно один раз; в более ранних версиях это могло быть вычислено более одного раза.

bool  SvPVXtrue(SV *sv)
SvREADONLY

Возвращает true, если аргумент только для чтения, иначе false. Доступно для perl-кода через Internals::SvREADONLY().

U32  SvREADONLY(SV* sv)
SvREADONLY_off

Отмечает объект как не-только-для-чтения. Точное значение зависит от типа объекта. Доступно для perl-кода через Internals::SvREADONLY().

U32  SvREADONLY_off(SV* sv)
SvREADONLY_on

Отмечает объект как только для чтения. Точное значение зависит от типа объекта. Доступно для perl-кода через Internals::SvREADONLY().

U32  SvREADONLY_on(SV* sv)
sv_ref

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

dst может быть SV, который будет установлен на описание, или NULL, в этом случае возвращается временный SV.

Если ob истинно и SV благословлён, описанием является имя класса, в противном случае — тип SV, "SCALAR", "ARRAY" и т. д.

SV *  sv_ref(SV *dst, const SV * const sv, const int ob)
SvREFCNT

Возвращает значение счётчика ссылок объекта. Доступно для perl-кода через Internals::SvREFCNT().

U32  SvREFCNT(SV* sv)
SvREFCNT_dec
SvREFCNT_dec_set_NULL
SvREFCNT_dec_ret_NULL
SvREFCNT_dec_NN

Эти функции декрементируют счётчик ссылок данного SV.

SvREFCNT_dec_NN может быть использовано только тогда, когда sv известно, что не является NULL.

Функция SvREFCNT_dec_ret_NULL() идентична SvREFCNT_dec() за исключением того, что она возвращает NULL SV *. Она используется макросом SvREFCNT_dec_set_NULL(), который, при передаче ненулевого аргумента, декрементирует счётчик ссылок аргумента и устанавливает его в NULL. Вы можете заменить код следующего вида:

if (sv) {
   SvREFCNT_dec_NN(sv);
   sv = NULL;
}

на

SvREFCNT_dec_set_NULL(sv);
void  SvREFCNT_dec         (SV *sv)
void  SvREFCNT_dec_set_NULL(SV *sv)
SV *  SvREFCNT_dec_ret_NULL(SV *sv)
void  SvREFCNT_dec_NN      (SV *sv)
SvREFCNT_inc
SvREFCNT_inc_NN
SvREFCNT_inc_simple
SvREFCNT_inc_simple_NN
SvREFCNT_inc_simple_void
SvREFCNT_inc_simple_void_NN
SvREFCNT_inc_void
SvREFCNT_inc_void_NN

Все они увеличивают счётчик ссылок заданного SV. Те, у которых в имени нет void, возвращают SV.

SvREFCNT_inc — базовая операция; остальные — оптимизации, если известны различные ограничения на входные данные; следовательно, все они могут быть заменены на SvREFCNT_inc.

SvREFCNT_inc_NN может быть использовано только если вы знаете, что sv не NULL. Поскольку нам не нужно проверять на NULL, это быстрее и меньше.

SvREFCNT_inc_void может быть использовано только если вам не нужно значение возврата. Макрос не обязан возвращать осмысленное значение.

SvREFCNT_inc_void_NN может быть использовано только если вам не нужно значение возврата, и вы знаете, что sv не NULL. Макрос не обязан возвращать осмысленное значение или проверять на NULL, поэтому он меньше и быстрее.

SvREFCNT_inc_simple может быть использовано только с выражениями без побочных эффектов. Поскольку нам не нужно сохранять временное значение, это быстрее.

SvREFCNT_inc_simple_NN может быть использовано только с выражениями без побочных эффектов, и вы знаете, что sv не NULL. Поскольку нам не нужно сохранять временное значение, ни проверять на NULL, это быстрее и меньше.

SvREFCNT_inc_simple_void может быть использовано только с выражениями без побочных эффектов, и вам не нужно значение возврата.

SvREFCNT_inc_simple_void_NN может быть использовано только с выражениями без побочных эффектов, вам не нужно значение возврата, и вы знаете, что sv не NULL. 

SV *  SvREFCNT_inc               (SV *sv)
SV *  SvREFCNT_inc_NN            (SV *sv)
SV*   SvREFCNT_inc_simple        (SV* sv)
SV*   SvREFCNT_inc_simple_NN     (SV* sv)
void  SvREFCNT_inc_simple_void   (SV* sv)
void  SvREFCNT_inc_simple_void_NN(SV* sv)
void  SvREFCNT_inc_void          (SV *sv)
void  SvREFCNT_inc_void_NN       (SV* sv)
sv_reftype

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

Если ob — true, и SV благословлён, строка — имя класса, иначе — тип SV, "SCALAR", "ARRAY" и т. д.

const char *  sv_reftype(const SV * const sv, const int ob)
sv_replace

Делает первый аргумент копией второго, затем удаляет оригинал. Целевой SV физически принимает на себя владение телом исходного SV и наследует его флаги; однако, целевой SV сохраняет любую магию, которой он владеет, а любая магия в источнике отбрасывается. Обратите внимание, что это специализированная операция копирования SV; в большинстве случаев вы захотите использовать sv_setsv или один из его многочисленных макросов.

void  sv_replace(SV * const sv, SV * const nsv)
sv_report_used

Выводит содержимое всех SV, ещё не освобождённых (помощь при отладке).

void  sv_report_used()
sv_reset

Базовая реализация для функции Perl reset. Обратите внимание, что функция на уровне Perl слегка устарела.

void  sv_reset(const char *s, HV * const stash)
SvROK

Проверяет, является ли SV RV.

U32  SvROK(SV* sv)
SvROK_off

Сбрасывает статус RV SV.

void  SvROK_off(SV* sv)
SvROK_on

Указывает SV, что он является RV.

void  SvROK_on(SV* sv)
SvRV

Разъём RV, чтобы вернуть SV.

SV*  SvRV(SV* sv)
SvRV_set

Устанавливает значение указателя RV в sv на val. См. "SvIV_set". 

void  SvRV_set(SV* sv, SV* val)
sv_rvunweaken

Отмена ослабления ссылки: очистка флага SvWEAKREF на этом RV; удаление обратной ссылки на этот RV из массива обратных ссылок, связанных с целевым SV, увеличение счётчика ссылок целевого объекта. Безмолвно игнорирует undef, и предупреждает о ссылках, не являющихся слабыми.

SV *  sv_rvunweaken(SV * const sv)
sv_rvweaken

Ослабление ссылки: установка флага SvWEAKREF на этом RV; предоставление целевому SV PERL_MAGIC_backref магии, если она ещё не установлена; и добавление обратной ссылки на этот RV в массив обратных ссылок, связанных с этой магией. Если RV магический, вызов magic set после того, как RV будет очищен. Безмолвно игнорирует undef, и предупреждает об уже слабых ссылках.

SV *  sv_rvweaken(SV * const sv)
sv_setbool
sv_setbool_mg

Эти функции устанавливают SV в логическое значение true или false, если это необходимо, сначала повышая его тип.

Они отличаются только тем, что sv_setbool_mg обрабатывает магию 'set'; sv_setbool — нет.

void  sv_setbool(SV *sv, bool b)
sv_set_bool

Эквивалентно sv_setsv(sv, bool_val ? &Pl_sv_yes : &PL_sv_no), но может быть сделано более эффективным в будущем. Не обрабатывает магию set.

Эквивалент в Perl — $sv = !!$expr;.

Введено в Perl 5.35.11.

void  sv_set_bool(SV *sv, const bool bool_val)
sv_set_false

Эквивалентно sv_setsv(sv, &PL_sv_no), но может быть сделано более эффективным в будущем. Не обрабатывает магию set.

Эквивалент в Perl — $sv = !1;.

Введено в Perl 5.35.11.

void  sv_set_false(SV *sv)
sv_setiv
sv_setiv_mg

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

Они отличаются только тем, что sv_setiv_mg обрабатывает магию 'set'; sv_setiv — нет.

void  sv_setiv   (SV * const sv, const IV num)
void  sv_setiv_mg(SV * const sv, const IV i)
SvSETMAGIC

Вызывает "mg_set" на SV, если у него есть магия 'set'. Это необходимо после модификации скаляра, если это магическая переменная, например $|, или привязанная переменная (она вызывает STORE). Этот макрос вычисляет свой аргумент более одного раза.

void  SvSETMAGIC(SV* sv)
SvSetMagicSV
SvSetMagicSV_nosteal
SvSetSV
SvSetSV_nosteal

Если dsv равно ssv, эти функции ничего не делают. В противном случае все они вызывают какой-то вид "sv_setsv". Они могут вычислять свои аргументы более одного раза.

Единственные различия:

SvSetMagicSV и SvSetMagicSV_nosteal выполняют необходимую магию 'set' впоследствии над целевым SV; SvSetSV и SvSetSV_nosteal этого не делают.

SvSetSV_nosteal и SvSetMagicSV_nosteal вызывают неразрушающую версию sv_setsv.

void  SvSetMagicSV(SV* dsv, SV* ssv)
sv_setnv
sv_setnv_mg

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

Они отличаются только тем, что sv_setnv_mg обрабатывает магию 'set'; sv_setnv — нет.

void  sv_setnv(SV * const sv, const NV num)
sv_setpv
sv_setpv_mg
sv_setpvn
sv_setpvn_fresh
sv_setpvn_mg
sv_setpvs
sv_setpvs_mg

Эти функции копируют строку в SV sv, убеждаясь, что он "SvPOK_only".

В формах pvs, строка должна быть C-литеральной строкой, заключённой в двойные кавычки.

В формах pvn, первый байт строки указывается переменной ptr, а len указывает количество байтов, которые должны быть скопированы, потенциально включая вложенные NUL символы.

В простых формах pv, ptr указывает на завершающуюся нулём C-строку. То есть, она указывает на первый байт строки, а копирование продолжается до первого встреченного NUL байта.

В формах, принимающих аргумент ptr, если он NULL, SV станет неопределённым.

Флаг UTF-8 не изменяется этими функциями. В результате гарантируется завершающий нулевой байт.

Формы _mg обрабатывают магию 'set'; другие формы пропускают всю магию.

sv_setpvn_fresh — сокращённая альтернатива sv_setpvn, предназначенная ТОЛЬКО для использования с новым SV, который был повышен до SVt_PV, SVt_PVIV, SVt_PVNV или SVt_PVMG.

void  sv_setpv       (SV * const sv, const char * const ptr)
void  sv_setpv_mg    (SV * const sv, const char * const ptr)
void  sv_setpvn      (SV * const sv, const char * const ptr,
                      const STRLEN len)
void  sv_setpvn_fresh(SV * const sv, const char * const ptr,
                      const STRLEN len)
void  sv_setpvn_mg   (SV * const sv, const char * const ptr,
                      const STRLEN len)
void  sv_setpvs      (SV* sv, "literal string")
void  sv_setpvs_mg   (SV* sv, "literal string")
sv_setpv_bufsize

Устанавливает SV в строку длиной cur байтов, с доступностью по крайней мере len байтов. Гарантирует, что в SvEND находится нулевой байт. Возвращает указатель char * на буфер SvPV.

char  *  sv_setpv_bufsize(SV * const sv, const STRLEN cur,
                          const STRLEN len)
sv_setpvf
sv_setpvf_mg
sv_setpvf_mg_nocontext
sv_setpvf_nocontext

Они работают так же, как "sv_catpvf", но копируют текст в SV вместо добавления.

Различия между ними:

sv_setpvf_mg и sv_setpvf_mg_nocontext выполняют магию 'set'; sv_setpvf и sv_setpvf_nocontext пропускают всю магию.

sv_setpvf_nocontext и sv_setpvf_mg_nocontext не принимают параметр контекста потока (aTHX), поэтому используются в ситуациях, когда вызывающая функция уже не имеет контекста потока.

ПРИМЕЧАНИЕ: sv_setpvf должен быть явно вызван как Perl_sv_setpvf с параметром aTHX_.

ПРИМЕЧАНИЕ: sv_setpvf_mg должен быть явно вызван как Perl_sv_setpvf_mg с параметром aTHX_. 

void  Perl_sv_setpvf        (pTHX_ SV * const sv,
                             const char * const pat, ...)
void  Perl_sv_setpvf_mg     (pTHX_ SV * const sv,
                             const char * const pat, ...)
void  sv_setpvf_mg_nocontext(SV * const sv,
                             const char * const pat, ...)
void  sv_setpvf_nocontext   (SV * const sv,
                             const char * const pat, ...)
sv_setref_iv

Копирует целое число в новый SV, необязательно благословляя его. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для благословения. Установите classname в NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

SV *  sv_setref_iv(SV * const rv, const char * const classname,
                   const IV iv)
sv_setref_nv

Копирует двойное значение в новый SV, необязательно благословляя его. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для благословения. Установите classname в NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

SV *  sv_setref_nv(SV * const rv, const char * const classname,
                   const NV nv)
sv_setref_pv

Копирует указатель в новый SV, необязательно благословляя SV. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Если аргумент pv равен NULL, то PL_sv_undef будет помещён в SV. Аргумент classname указывает пакет для благословения. Установите classname в NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и будет возвращён RV.

Не используйте с другими типами Perl, такими как HV, AV, SV, CV, потому что эти объекты могут быть повреждены процессом копирования указателя.

Обратите внимание, что sv_setref_pvn копирует строку, в то время как эта функция копирует указатель.

SV *  sv_setref_pv(SV * const rv, const char * const classname,
                   void * const pv)
sv_setref_pvn

Копирует строку в новый SV, необязательно благословляя SV. Длина строки должна быть указана с помощью n. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для благословения. Установите classname в NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и будет возвращён RV.

Обратите внимание, что sv_setref_pv копирует указатель, в то время как эта функция копирует строку.

SV *  sv_setref_pvn(SV * const rv, const char * const classname,
                    const char * const pv, const STRLEN n)
sv_setref_pvs

Подобно sv_setref_pvn, но принимает литерную строку вместо пары строка/длина.

SV *  sv_setref_pvs(SV *const rv, const char *const classname,
                    "literal string")
sv_setref_uv

Копирует целое беззнаковое число в новый SV, необязательно благословляя SV. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для благословения. Установите classname в NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и будет возвращён RV.

SV *  sv_setref_uv(SV * const rv, const char * const classname,
                   const UV uv)
sv_setrv_inc
sv_setrv_inc_mg

Как sv_setrv_noinc, но увеличивает счётчик ссылок ref.

sv_setrv_inc_mg вызовет магия 'set' для SV; sv_setrv_inc не будет.

void  sv_setrv_inc(SV * const sv, SV * const ref)
sv_setrv_noinc
sv_setrv_noinc_mg

Копирует указатель SV в данный SV в качестве ссылки SV, преобразуя её при необходимости. После этого, SvRV(sv) равно ref. Это не изменяет счётчик ссылок ref. Ссылка ref не должна быть NULL.

sv_setrv_noinc_mg вызовет магия 'set' для SV; sv_setrv_noinc не будет.

void  sv_setrv_noinc(SV * const sv, SV * const ref)
sv_setsv
sv_setsv_flags
sv_setsv_mg
sv_setsv_nomg

Эти функции копируют содержимое исходного SV ssv в целевой SV dsv. ssv может быть уничтожен, если он смертный, поэтому не используйте эти функции, если исходный SV нужно повторно использовать. Грубо говоря, они выполняют копирование по значению, уничтожая предыдущее содержимое цели.

Они отличаются только тем, что:

sv_setsv вызывает магия 'get' для ssv, но пропускает магия 'set' для dsv.

sv_setsv_mg вызывает как магия 'get' для ssv, так и магия 'set' для dsv.

sv_setsv_nomg пропускает всю магии.

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

Вероятно, вам следует использовать один из набора оберток, таких как "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" и "SvSetMagicSV_nosteal".

sv_setsv_flags - это основная функция для копирования скаляров, и большинство других функций/макросов копирования используют её внутри.

void  sv_setsv      (SV *dsv, SV *ssv)
void  sv_setsv_flags(SV *dsv, SV *ssv, const I32 flags)
void  sv_setsv_mg   (SV * const dsv, SV * const ssv)
void  sv_setsv_nomg (SV *dsv, SV *ssv)
sv_set_true

Эквивалентно sv_setsv(sv, &PL_sv_yes), но в будущем может быть сделано более эффективным. Не обрабатывает магия 'set'.

Эквивалент на Perl - $sv = !0;.

Введено в perl 5.35.11.

void  sv_set_true(SV *sv)
sv_set_undef

Эквивалентно sv_setsv(sv, &PL_sv_undef), но более эффективно. Не обрабатывает магия 'set'.

Эквивалент на Perl - $sv = undef;. Обратите внимание, что он не освобождает буфер строки, в отличие от undef $sv.

Введено в perl 5.25.12.

void  sv_set_undef(SV *sv)
sv_setuv
sv_setuv_mg

Эти функции копируют целое беззнаковое число в данный SV, предварительно преобразовав его, если необходимо.

Они отличаются только тем, что sv_setuv_mg обрабатывает магия 'set'; sv_setuv - нет.

void  sv_setuv   (SV * const sv, const UV num)
void  sv_setuv_mg(SV * const sv, const UV u)
SvSHARE

Организует совместное использование sv между потоками, если загружен подходящий модуль.

void  SvSHARE(SV* sv)
SvSHARED_HASH

Возвращает хэш для sv, созданный "newSVpvn_share".

struct hek*  SvSHARED_HASH(SV * sv)
SvSTASH

Возвращает стэш SV.

HV*  SvSTASH(SV* sv)
SvSTASH_set

Устанавливает значение указателя STASH в sv в val. См. "SvIV_set".

void  SvSTASH_set(SV* sv, HV* val)
sv_streq

Удобный ярлык для вызова sv_streq_flags с флагом SV_GMAGIC.

Функция ведет себя примерно как Perl-код $sv1 eq $sv2. 

bool  sv_streq(SV *sv1, SV *sv2)
sv_streq_flags

Возвращает булево значение, указывающее, идентичны ли строки в двух SV. Если у аргумента flags установлен бит SV_GMAGIC, он также обрабатывает get-магию. При необходимости приведёт аргументы к строкам. Обращается с NULL как с undef. Правильно обрабатывает флаг UTF8.

Если у flags не установлен бит SV_SKIP_OVERLOAD, будет выполнена попытка использования перегрузки eq. Если такая перегрузка не существует или флаг установлен, вместо этого будет использовано обычное сравнение строк.

bool  sv_streq_flags(SV *sv1, SV *sv2, const U32 flags)
SvTRUE
SvTRUE_NN
SvTRUE_nomg
SvTRUE_nomg_NN
SvTRUEx

Эти функции возвращают булево значение, указывающее, интерпретируется ли Perl SV как истина или ложь. См. "SvOK" для проверки определённости/неопределённости.

Начиная с Perl 5.32, все гарантированно оценивают sv только один раз. До этого релиза только SvTRUEx гарантировало однократную оценку; теперь SvTRUEx идентично SvTRUE.

SvTRUE_nomg и TRUE_nomg_NN не выполняют магии 'get'; остальные - да, если скаляр не является уже SvPOK, SvIOK, или SvNOK (публичные, не приватные флаги).

SvTRUE_NN подобна "SvTRUE", но предполагается, что sv не является NULL (NN). Если есть вероятность, что он NULL, используйте обычную SvTRUE.

SvTRUE_nomg_NN подобна "SvTRUE_nomg", но предполагается, что sv не является NULL (NN). Если есть вероятность, что он NULL, используйте обычную SvTRUE_nomg.

bool  SvTRUE(SV *sv)
SvTYPE

Возвращает тип SV. См. "svtype".

svtype  SvTYPE(SV* sv)
SvUNLOCK

Освобождает взаимную блокировку на sv если загружен подходящий модуль.

void  SvUNLOCK(SV* sv)
sv_unmagic

Удаляет всю магии типа type из SV.

int  sv_unmagic(SV * const sv, const int type)
sv_unmagicext

Удаляет всю магии типа type со специфицированным vtbl из SV.

int  sv_unmagicext(SV * const sv, const int type,
                   const MGVTBL *vtbl)
sv_unref

Снимает статус RV у SV и уменьшает счётчик ссылок того, на что ссылался RV. Это практически обратное newSVrv. Это sv_unref_flags со значением flag равным нулю. См. "SvROK_off".

void  sv_unref(SV *sv)
sv_unref_flags

Снимает статус RV у SV и уменьшает счётчик ссылок того, на что ссылался RV. Это практически обратное newSVrv. Аргумент cflags может содержать SV_IMMEDIATE_UNREF для принудительного уменьшения счётчика ссылок (в противном случае уменьшение происходит только если счётчик ссылок отличен от одного или ссылка является только для чтения).

См. "SvROK_off".

void  sv_unref_flags(SV * const ref, const U32 flags)
SvUOK

Возвращает булево значение, указывающее, содержит ли SV целое число, которое должно быть интерпретировано как беззнаковое. Целое неотрицательное значение, попадающее в диапазон IV и UV, может быть помечено либо как SvUOK, либо как SvIOK.

bool  SvUOK(SV* sv)
SvUPGRADE

Используется для повышения уровня SV до более сложной формы. Использует sv_upgrade для выполнения повышения, если необходимо. См. "svtype".

void  SvUPGRADE(SV* sv, svtype type)
sv_upgrade

Повышает уровень SV до более сложной формы. Обычно добавляет новый тип тела в SV, затем копирует как можно больше информации из старого тела. Вызывает ошибку, если SV уже имеет более сложную форму, чем требуется. Обычно вы хотите использовать оберточку макроса SvUPGRADE, которая проверяет тип перед вызовом sv_upgrade, и поэтому не вызывает ошибку. См. также "svtype".

void  sv_upgrade(SV * const sv, svtype new_type)
sv_usepvn
sv_usepvn_flags
sv_usepvn_mg

Эти функции сообщают SV использовать ptr в качестве своего строкового значения. Обычно строка хранится внутри SV, но эти функции сообщают SV использовать внешнюю строку.

ptr должен указывать на память, выделенную функцией "Newx". Это должно быть начало Newx-блока памяти, а не указатель на середину блока (будьте осторожны с OOK и копированием при записи). Также указатель не должен быть получен из не-Newx-аллокатора, такого как malloc. Длина строки, len, также должна быть указана. По умолчанию эта функция будет "Renew" (т.е. перевыделять, перемещать) память по указателю ptr, поэтому после передачи указателя функции sv_usepvn его нельзя освобождать или использовать программистом, а также нельзя использовать указатели, находящиеся "за" этим указателем (например, ptr + 1).

В форме с sv_usepvn_flags, если flags & SV_SMAGIC истинно, то SvSETMAGIC вызывается перед возвратом. Если flags & SV_HAS_TRAILING_NUL истинно, то ptr[len] должно быть NUL, и перевыделение памяти будет пропущено (т.е., буфер фактически на 1 байт длиннее, чем len, и уже соответствует требованиям для хранения в SvPVX).

sv_usepvn просто sv_usepvn_flags с flags равным 0, поэтому магия 'set' пропускается.

sv_usepvn_mg просто sv_usepvn_flags с flags равным SV_SMAGIC, поэтому выполняется магия 'set'.

void  sv_usepvn      (SV *sv, char *ptr, STRLEN len)
void  sv_usepvn_flags(SV * const sv, char *ptr, const STRLEN len,
                      const U32 flags)
void  sv_usepvn_mg   (SV *sv, char *ptr, STRLEN len)
sv_utf8_decode

Если PV SV является последовательностью байтов в расширенном UTF-8 Perl и содержит многобайтовый символ, то флаг SvUTF8 устанавливается, чтобы он выглядел как один символ. Если PV содержит только однобайтовые символы, то флаг SvUTF8 остается выключенным. Проверяет PV на валидность UTF-8 и возвращает FALSE, если PV не является валидным UTF-8.

bool  sv_utf8_decode(SV * const sv)
sv_utf8_downgrade
sv_utf8_downgrade_flags
sv_utf8_downgrade_nomg

Эти функции пытаются преобразовать PV SV из символов в байты. Если PV содержит символ, который не может быть представлен одним байтом, преобразование завершится неудачей; в этом случае возвращается FALSE если fail_ok истинно; иначе они возвращают ошибку.

Это не универсальный интерфейс для преобразования Юникода в байты; используйте расширение Encode для этого.

Они отличаются только тем, что:

sv_utf8_downgrade обрабатывает магию 'get' для sv.

sv_utf8_downgrade_nomg не обрабатывает.

sv_utf8_downgrade_flags имеет дополнительный параметр flags, в котором можно указать SV_GMAGIC для обработки магии 'get', или оставить его не установленным, чтобы не обрабатывать 'get' магию.

bool  sv_utf8_downgrade      (SV * const sv, const bool fail_ok)
bool  sv_utf8_downgrade_flags(SV * const sv, const bool fail_ok,
                              const U32 flags)
bool  sv_utf8_downgrade_nomg (SV * const sv, const bool fail_ok)
sv_utf8_encode

Преобразует PV SV в UTF-8, а затем отключает флаг SvUTF8, чтобы он снова выглядел как последовательность байтов.

void  sv_utf8_encode(SV * const sv)
SvUTF8_off

Снимает флаг UTF-8 для SV (данные не изменяются, только флаг). Не используйте слишком часто.

void  SvUTF8_off(SV *sv)
SvUTF8_on

Устанавливает флаг UTF-8 для SV (данные не изменяются, только флаг). Не используйте слишком часто.

void  SvUTF8_on(SV *sv)
sv_utf8_upgrade
sv_utf8_upgrade_flags
sv_utf8_upgrade_flags_grow
sv_utf8_upgrade_nomg

Эти функции преобразуют PV SV в его представление в кодировке UTF-8. SV приводится к строковому типу, если это не так. Они всегда устанавливают флаг SvUTF8, чтобы избежать будущих проверок валидности, даже если вся строка одинакова в UTF-8 и без него. Они возвращают количество байтов в преобразованной строке.

Формы различаются только двумя способами. Главное отличие — выполняется ли магия 'get' для sv. sv_utf8_upgrade_nomg пропускает 'get' магию; sv_utf8_upgrade её выполняет; а sv_utf8_upgrade_flags и sv_utf8_upgrade_flags_grow её выполняют (если бит SV_GMAGIC установлен в flags) или нет (если этот бит сброшен).

Другое различие заключается в том, что sv_utf8_upgrade_flags_grow имеет дополнительный параметр extra, который позволяет вызывающей стороне зарезервировать дополнительное пространство, помимо необходимого для фактического преобразования. Это используется, когда вызывающая сторона знает, что вскоре ей потребуется ещё больше места, и эффективнее запросить его от системы в одном вызове. Эта форма в остальном идентична sv_utf8_upgrade_flags.

Это не универсальный интерфейс для преобразования байтов в Юникод; для этого используйте расширение Encode.

Флаг SV_FORCE_UTF8_UPGRADE теперь игнорируется.

STRLEN  sv_utf8_upgrade           (SV *sv)
STRLEN  sv_utf8_upgrade_flags     (SV * const sv, const I32 flags)
STRLEN  sv_utf8_upgrade_flags_grow(SV * const sv, const I32 flags,
                                   STRLEN extra)
STRLEN  sv_utf8_upgrade_nomg      (SV *sv)
SvUTF8

Возвращает значение U32, обозначающее статус UTF-8 для SV. При правильной настройке это указывает, содержит ли SV данные в кодировке UTF-8. Вы должны использовать его после вызова "SvPV" или одной из его разновидностей, на случай, если вызов перегрузки строк обновит внутренний флаг.

Если вы хотите учесть прагму bytes, используйте "DO_UTF8" вместо этого.

U32  SvUTF8(SV* sv)
SvUV
SvUV_nomg
SvUVx

Каждая из этих функций принудительно преобразует заданный SV в UV и возвращает его. В многих случаях возвращаемое значение будет сохранёно в слоте UV sv, но не во всех. (Используйте "sv_setuv" чтобы убедиться, что это происходит).

Начиная с версии 5.37.1, все гарантированно оценивают sv только один раз.

SvUVx теперь идентична SvUV, но до версии 5.37.1, только она гарантированно оценивала sv только один раз.

UV  SvUV(SV *sv)
sv_2uv_flags

Возвращает целое беззнаковое значение SV, выполняя необходимые преобразования строк. Если у flags установлен бит SV_GMAGIC, выполняет mg_get() сначала. Обычно используется через макросы SvUV(sv) и SvUVx(sv).

UV  sv_2uv_flags(SV * const sv, const I32 flags)
SvUV_set

Устанавливает значение указателя UV в sv на val. См. "SvIV_set".

void  SvUV_set(SV* sv, UV val)
SvUVX

Возвращает исходное значение в слоте UV SV, без проверок или преобразований. Используйте только когда уверены, что SvIOK истинно. См. также "SvUV".

UV  SvUVX(SV* sv)
SvUVXx

DEPRECATED! Планируется удалить SvUVXx в будущей версии Perl. Не используйте в новом коде; удалите из существующего кода.

Это ненужный синоним для "SvUVX"

UV  SvUVXx(SV* sv)
sv_vcatpvf
sv_vcatpvf_mg

Эти функции обрабатывают свои аргументы как sv_vcatpvfn с непустым списком аргументов C-стиля и добавляют отформатированный вывод в sv.

Они отличаются только тем, что sv_vcatpvf_mg выполняет магию 'set'; sv_vcatpvf её пропускает.

Обе функции выполняют магию 'get'.

Обычно они вызываются через свои интерфейсы "sv_catpvf" и "sv_catpvf_mg".

void  sv_vcatpvf(SV * const sv, const char * const pat,
                 va_list * const args)
sv_vcatpvfn
sv_vcatpvfn_flags

Эти функции обрабатывают свои аргументы как vsprintf(3) и добавляют отформатированный вывод в SV. Они используют массив SVs, если список аргументов C-стиля отсутствует (NULL). Переупорядочивание аргументов (с использованием спецификаторов формата, таких как %2$d или %*2$d) поддерживается только при использовании массива SVs; использование списка аргументов C-стиля с строкой формата, использующей переупорядочивание аргументов, приведёт к исключению.

При включённой проверке безопасности, они указывают через maybe_tainted является ли результат недостоверным (часто из-за использования локалей).

Они предполагают, что pat имеет тот же статус utf8, что и sv. Ответственность за это лежит на вызывающей стороне.

Они отличаются тем, что sv_vcatpvfn_flags имеет параметр flags, который позволяет вызывающей стороне установить или сбросить флаги SV_GMAGIC и/или SV_SMAGIC, чтобы указать, какую магию обработать, а какую нет; в то время как обычная sv_vcatpvfn всегда обрабатывает магию 'get' и 'set'.

Они обычно используются через один из интерфейсов "sv_vcatpvf" и "sv_vcatpvf_mg".

void  sv_vcatpvfn      (SV * const sv, const char * const pat,
                        const STRLEN patlen, va_list * const args,
                        SV ** const svargs, const Size_t sv_count,
                        bool * const maybe_tainted)
void  sv_vcatpvfn_flags(SV * const sv, const char * const pat,
                        const STRLEN patlen, va_list * const args,
                        SV ** const svargs, const Size_t sv_count,
                        bool * const maybe_tainted,
                        const U32 flags)
SvVOK

Возвращает булево значение, указывающее, содержит ли SV v-строку.

bool  SvVOK(SV* sv)
sv_vsetpvf
sv_vsetpvf_mg

Эти функции работают как "sv_vcatpvf" но копируют текст в SV вместо добавления.

Они отличаются только тем, что sv_vsetpvf_mg выполняет магию 'set'; sv_vsetpvf пропускает всю магию.

Обычно они используются через свои интерфейсы "sv_setpvf" и "sv_setpvf_mg".

void  sv_vsetpvf(SV * const sv, const char * const pat,
                 va_list * const args)
sv_vsetpvfn

Работает как sv_vcatpvfn но копирует текст в SV вместо добавления.

Обычно используется через один из интерфейсов "sv_vsetpvf" и "sv_vsetpvf_mg".

void  sv_vsetpvfn(SV * const sv, const char * const pat,
                  const STRLEN patlen, va_list * const args,
                  SV ** const svargs, const Size_t sv_count,
                  bool * const maybe_tainted)
SvVSTRING_mg

Возвращает магию vstring, или NULL, если её нет.

MAGIC*  SvVSTRING_mg(SV * sv)
vnewSVpvf

Подобно "newSVpvf" но аргументы заключены в список аргументов.

SV *  vnewSVpvf(const char * const pat, va_list * const args)

Загрязнение

SvTAINT

Загрязняет SV, если включено загрязнение и какой-то ввод в текущее выражение загрязнено — обычно переменная, но, возможно, также неявные вводы, такие как настройки локали. SvTAINT распространяет это загрязнение на выводы выражения пессимистичным способом; т.е. без учёта того, какие выводы влияют на какие вводы.

void  SvTAINT(SV* sv)
SvTAINTED

Проверяет, загрязнено ли SV. Возвращает TRUE, если загрязнено, FALSE — если нет.

bool  SvTAINTED(SV* sv)
END_OF_DOCUMENT_MARKER
SvTAINTED_off

Снимает метку «загрязнён» с SV. Будьте очень осторожны с этой процедурой, так как она обходит некоторые фундаментальные функции безопасности Perl. Авторы модулей XS не должны использовать эту функцию, если они не полностью понимают все последствия безусловного снятия метки «загрязнён» с значения. Снятие метки «загрязнён» должно выполняться стандартным способом Perl, с помощью тщательно составленной регулярной выражения, а не непосредственным снятием метки с переменных.

void  SvTAINTED_off(SV* sv)
SvTAINTED_on

Помечает SV как «загрязнённый», если включена функция проверки на загрязнение.

void  SvTAINTED_on(SV* sv)

Время

ASCTIME_R_PROTO

Этот символ кодирует прототип asctime_r. Он равен нулю, если d_asctime_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из reentr.h, если d_asctime_r определён.

CTIME_R_PROTO

Этот символ кодирует прототип ctime_r. Он равен нулю, если d_ctime_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из reentr.h, если d_ctime_r определён.

GMTIME_MAX

Этот символ содержит максимальное значение смещения time_t для функции gmtime (), и по умолчанию равен 0.

GMTIME_MIN

Этот символ содержит минимальное значение смещения time_t для функции gmtime (), и по умолчанию равен 0.

GMTIME_R_PROTO

Этот символ кодирует прототип gmtime_r. Он равен нулю, если d_gmtime_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из reentr.h, если d_gmtime_r определён.

HAS_ASCTIME_R

Если этот символ определён, это указывает на доступность функции asctime_r в режиме повторного входа.

HAS_ASCTIME64

Если этот символ определён, это указывает на доступность функции asctime64 () для выполнения 64-битной версии asctime ()

HAS_CTIME_R

Если этот символ определён, это указывает на доступность функции ctime_r в режиме повторного входа.

HAS_CTIME64

Если этот символ определён, это указывает на доступность функции ctime64 () для выполнения 64-битной версии ctime ()

HAS_DIFFTIME

Если этот символ определён, это указывает на доступность функции difftime.

HAS_DIFFTIME64

Если этот символ определён, это указывает на доступность функции difftime64 () для выполнения 64-битной версии difftime ()

HAS_FUTIMES

Если этот символ определён, это указывает на доступность функции futimes для изменения временных меток дескрипторов файлов с помощью struct timevals.

HAS_GETITIMER

Если этот символ определён, это указывает на доступность функции getitimer для возврата таймеров интервалов.

HAS_GETTIMEOFDAY

Если этот символ определён, это указывает на доступность системного вызова gettimeofday() для получения часов с точностью до долей секунды. Обычно необходимо включить файл sys/resource.h (см. "I_SYS_RESOURCE"). Для ссылки на «struct timeval» следует использовать тип «Timeval».

HAS_GMTIME_R

Если этот символ определён, это указывает на доступность функции gmtime_r в режиме повторного входа.

HAS_GMTIME64

Если этот символ определён, это указывает на доступность функции gmtime64 () для выполнения 64-битной версии gmtime ()

HAS_LOCALTIME_R

Если этот символ определён, это указывает на доступность функции localtime_r в режиме повторного входа.

HAS_LOCALTIME64

Если этот символ определён, это указывает на доступность функции localtime64 () для выполнения 64-битной версии localtime ()

HAS_MKTIME

Если этот символ определён, это указывает на доступность функции mktime.

HAS_MKTIME64

Если этот символ определён, это указывает на доступность функции mktime64 () для выполнения 64-битной версии mktime ()

HAS_NANOSLEEP

Если этот символ определён, это указывает на доступность системного вызова nanosleep для сна с точностью до 1E-9 сек.

HAS_SETITIMER

Если этот символ определён, это указывает на доступность функции setitimer для установки таймеров интервалов.

HAS_STRFTIME

Если этот символ определён, это указывает на доступность функции strftime для форматирования времени.

HAS_TIME

Если этот символ определён, это указывает на существование функции time().

HAS_TIMEGM

Если этот символ определён, это указывает на доступность функции timegm для выполнения операции, обратной gmtime ()

HAS_TIMES

Если этот символ определён, это указывает на существование функции times(). Обратите внимание, что на некоторых системах (SUNOS) она устарела, и теперь используется getrusage(). Возможно, потребуется включить sys/times.h.

HAS_TM_TM_GMTOFF

Если этот символ определён, это указывает C-программе, что struct tm имеет поле tm_gmtoff.

HAS_TM_TM_ZONE

Если этот символ определён, это указывает C-программе, что struct tm имеет поле tm_zone.

HAS_TZNAME

Если этот символ определён, это указывает на доступность массива tzname[] для доступа к именам часовых поясов.

HAS_USLEEP

Если этот символ определён, это указывает на доступность функции usleep для приостановки процесса с точностью до долей секунды.

HAS_USLEEP_PROTO

Если этот символ определён, это указывает, что система предоставляет прототип для функции usleep(). В противном случае программа должна предоставить его самостоятельно. Хорошим предположением является

extern int usleep(useconds_t);
I_TIME

Этот символ всегда определён и указывает C-программе, что ей следует включить time.h.

#ifdef I_TIME
    #include <time.h>
#endif
I_UTIME

Если этот символ определён, это указывает C-программе, что ей следует включить utime.h.

#ifdef I_UTIME
    #include <utime.h>
#endif
LOCALTIME_MAX

Этот символ содержит максимальное значение смещения time_t для функции localtime (), и по умолчанию равен 0.

LOCALTIME_MIN

Этот символ содержит минимальное значение смещения time_t для функции localtime (), и по умолчанию равен 0.

LOCALTIME_R_NEEDS_TZSET

В большинстве реализаций libc функция localtime_r не вызывает tzset, что отличает их от localtime(), и делает изменение часового пояса с помощью $ENV{TZ} без явного вызова tzset невозможным. Этот символ заставляет нас вызывать tzset перед localtime_r

LOCALTIME_R_PROTO

Этот символ кодирует прототип localtime_r. Он равен нулю, если d_localtime_r не определён, и одному из макросов REENTRANT_PROTO_T_ABC из reentr.h, если d_localtime_r определён.

L_R_TZSET

Если localtime_r() нуждается в tzset, он определён в этом определении.

mini_mktime

Нормализует значения struct tm без семантики (и накладных расходов) localtime() функции mktime().

void  mini_mktime(struct tm *ptm)
my_strftime

strftime(), но с другим API, так что возвращаемое значение — указатель на отформатированный результат (который ОБЯЗАТЕЛЬНО должен быть освобождён вызывающей стороной). Это позволяет этой функции увеличивать размер буфера по мере необходимости, чтобы вызывающая сторона не должна была об этом заботиться.

При ошибке возвращает NULL.

Обратите внимание, что значения yday и wday фактически игнорируются этой функцией, так как mini_mktime() перезаписывает их.

Также обратите внимание, что она всегда выполняется в базовом LC_TIME языке программы, давая результаты, основанные на этом языке.

char *  my_strftime(const char *fmt, int sec, int min, int hour,
                    int mday, int mon, int year, int wday,
                    int yday, int isdst)
switch_to_global_locale

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

Она предназначена для того, чтобы Perl можно было безопасно использовать с C-библиотеками, которые обращаются к глобальной локали и которые не могут быть переконфигурированы для отказа от обращения к ней. По сути, это означает библиотеки, которые вызывают setlocale(3) на системах, не являющихся Windows. (Для портативности рекомендуется использовать её и на Windows.)

Недостатки использования этой функции заключаются в том, что она отключает сервисы, предоставляемые Perl для сокрытия проблем с локалью из вашего кода. Вероятно, вас больше всего будет беспокоить символ разделителя разрядов (десятичная точка) в числах с плавающей точкой. Код, выполненный после вызова этой функции, больше не может просто предполагать, что этот символ верен для текущих обстоятельств.

Чтобы вернуть управление Perl и перезапустить сервисы предотвращения проблем с локалью, вызовите "sync_locale". Поведение любого чисто Perl-кода, выполняемого во время действия этого переключения, не определено.

Глобальная локаль и локаль каждого потока независимы. Пока только один поток переходит в глобальную локаль, всё работает гладко. Но если это делают более одного, они легко могут мешать друг другу, и вероятны гонки. На системах Windows до Visual Studio 15 (в котором Microsoft исправила ошибку) гонки могут возникать (даже если только один поток был переведён в глобальную локаль), но только если вы используете следующие операции:

POSIX::localeconv
I18N::Langinfo, элементы CRNCYSTR и THOUSEP
"Perl_langinfo" в perlapi, элементы CRNCYSTR и THOUSEP

Первый элемент не поддаётся исправлению (кроме как обновлением до более поздней версии Visual Studio), но было бы возможно обойти два последних элемента, заставив Perl изменить свой алгоритм вычисления этих элементов, используя функции API Windows (вероятно, GetNumberFormat и GetCurrencyFormat); предложения по исправлениям приветствуются.

Код XS никогда не должен вызывать обычную setlocale, но вместо этого должен быть преобразован для вызова Perl_setlocale (которая является прямым заменителем системной функции setlocale) или использовать методы, описанные в perlcall для вызова POSIX::setlocale. Любой из этих вариантов прозрачно и корректно обработает все случаи однопоточности/многопоточности, поддерживаются ли POSIX 2008 или нет.

void  switch_to_global_locale()
sync_locale

Эта функция копирует состояние глобальной локали программы в вызывающий поток, переключает этот поток на использование локалей каждого потока, если это не было сделано ранее, и платформа их поддерживает. Локаль LC_NUMERIC переключается в стандартное состояние (используя соглашения C-локали), если она не находится в лексическом блоке use locale.

Perl теперь будет считать, что он управляет локалью.

Так как у однопоточных Perl'ей есть только глобальная локаль, эта функция является пустой операцией без потоков.

Эта функция предназначена для использования с C-библиотеками, которые выполняют манипуляции с локалью. Она позволяет Perl адаптироваться к их использованию. Вызовите эту функцию перед возвратом в Perl-пространство, чтобы он знал, в каком состоянии C-код оставил вещи.

Код XS не должен самостоятельно манипулировать локалью. Вместо этого, Perl_setlocale может быть использован в любое время для запроса или изменения локали (хотя изменение локали является нежелательным и опасным в многопоточных системах, которые не имеют многопоточно-безопасных операций с локалью. (См. "Многопоточная работа" в perllocale).

Избегайте использования функции libc setlocale(3). Тем не менее, некоторые библиотеки, не являющиеся Perl, вызываемые из XS, её вызывают, и их поведение может быть не изменяемым. Эта функция, наряду с "switch_to_global_locale", может использоваться для обеспечения бесшовного поведения в этих обстоятельствах, если задействован только один поток.

Если библиотека предоставляет возможность выключения её манипуляций с локалью, это предпочтительнее, чем использование этого механизма. Gtk является такой библиотекой.

Возвращаемое значение — логическое значение: TRUE, если глобальная локаль на момент вызова была активна для вызывающего потока; и FALSE, если была активна локаль каждого потока.

bool  sync_locale()

Типы имен

DB_Hash_t

Этот символ содержит тип элемента структуры префикса в заголовочном файле db.h. В более старых версиях DB это был int, а в новых — size_t.

DB_Prefix_t

Этот символ содержит тип элемента структуры префикса в заголовочном файле db.h. В более старых версиях DB это был int, а в новых — u_int32_t.

Direntry_t

Этот символ имеет значение 'struct direct' или 'struct dirent' в зависимости от доступности dirent. Вы должны использовать этот псевдотип для портативного объявления ваших записей каталога.

Fpos_t

Этот символ содержит тип, используемый для объявления позиций файлов в libc. Это может быть fpos_t, long, uint и т.д. Возможно, потребуется включить sys/types.h для получения любой информации typedef.

Free_t

Эта переменная содержит возвращаемый тип free(). Обычно это void, но иногда int.

Gid_t

Этот символ содержит возвращаемый тип getgid() и тип аргумента для setrgid() и родственных функций. Обычно это тип идентификаторов групп в ядре. Это может быть int, ushort, gid_t, и т.д. Возможно, потребуется включить sys/types.h для получения любой информации typedef.

Gid_t_f

Этот символ определяет строку формата, используемую для вывода Gid_t.

Gid_t_sign

Этот символ содержит знаковый бит Gid_t. 1 для беззнакового, -1 для знакового.

Gid_t_size

Этот символ содержит размер Gid_t в байтах.

Groups_t

Этот символ содержит тип, используемый для второго аргумента getgroups() и setgroups(). Обычно это то же самое, что и gidtype (gid_t), но иногда нет. Это может быть int, ushort, gid_t, и т.д. Возможно, потребуется включить sys/types.h для получения любой информации typedef. Это необходимо только если у вас есть getgroups() или setgroups().

Malloc_t

Этот символ является типом указателя, возвращаемого функциями malloc и realloc.

Mmap_t

Этот символ содержит возвращаемый тип системного вызова mmap() (и одновременно тип первого аргумента). Обычно он устанавливается в 'void *' или 'caddr_t'.

Mode_t

Этот символ содержит тип, используемый для объявления режимов файлов в системных вызовах. Обычно это mode_t, но может быть int или unsigned short. Возможно, потребуется включить sys/types.h для получения любой информации typedef.

Netdb_hlen_t

Этот символ содержит тип, используемый для второго аргумента gethostbyaddr().

Netdb_host_t

Этот символ содержит тип, используемый для первого аргумента gethostbyaddr().

Netdb_name_t

Этот символ содержит тип, используемый для аргумента gethostbyname().

Netdb_net_t

Этот символ содержит тип, используемый для первого аргумента getnetbyaddr().

Off_t

Этот символ содержит тип, используемый для объявления смещений в ядре. Это может быть int, long, off_t, и т.д. Возможно, потребуется включить sys/types.h для получения любой информации typedef.

Off_t_size

Этот символ содержит количество байт, используемых Off_t.

Pid_t

Этот символ содержит тип, используемый для объявления идентификаторов процессов в ядре. Это может быть int, uint, pid_t, и т.д. Возможно, потребуется включить sys/types.h для получения любой информации typedef.

Rand_seed_t

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

Select_fd_set_t

Этот символ содержит тип, используемый для второго, третьего и четвёртого аргументов select. Обычно это 'fd_set *', если HAS_FD_SET определён, и 'int *' в противном случае. Это полезно только если у вас есть select(), конечно.

Shmat_t

Этот символ содержит возвращаемый тип системного вызова shmat(). Обычно устанавливается в 'void *' или 'char *'.

Signal_t

Значение этого символа — либо "void", либо "int", соответствующие соответствующим возвращаемым типам обработчика сигнала. Таким образом, вы можете объявить обработчик сигнала, используя "Signal_t (*handler)()", и определить обработчик, используя "Signal_t handler(sig)".

Size_t

Этот символ содержит тип, используемый для объявления параметров длины для функций обработки строк. Обычно это size_t, но может быть unsigned long, int и т.д. Возможно, потребуется включить sys/types.h для получения любой информации typedef.

Size_t_size

Этот символ содержит размер Size_t в байтах.

Sock_size_t

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

SSize_t

Этот символ содержит тип, используемый функциями, которые возвращают количество байтов или код ошибки. Он должен быть знаковым типом. Обычно это ssize_t, но может быть long или int и т.д. Возможно, потребуется включить sys/types.h или unistd.h для получения любой информации typedef. Мы выберем тип такой, что sizeof(SSize_t) == sizeof(Size_t).

Time_t

Этот символ содержит тип, возвращаемый time() . Он может быть long или time_t на сайтах BSD (в этом случае sys/types.h должен быть включён).

Uid_t

Этот символ хранит тип, используемый для объявления идентификаторов пользователей в ядре. Это может быть int, ushort, uid_t, и т.д... Возможно, потребуется включить sys/types.h, чтобы получить любые типы.

Uid_t_f

Этот символ определяет строку формата, используемую для вывода Uid_t.

Uid_t_sign

Этот символ содержит информацию о знаковом типе Uid_t. 1 для беззнакового, -1 для знакового.

Uid_t_size

Этот символ хранит размер Uid_t в байтах.

Поддержка Unicode

"Поддержка Unicode" в perlguts содержит введение в этот API.

См. также "Character classification", "Character case changing", и "String Handling". Различные функции за пределами этого раздела также работают с Unicode. Поиск по строке "utf8" в этом документе.

BOM_UTF8

Это макрос, который вычисляет строковую константу байтов UTF-8, определяющих метку порядка байтов Unicode (U+FEFF) для платформы, на которой скомпилирован Perl. Это позволяет использовать мнемонику для этого символа, которая работает как на платформах ASCII, так и на EBCDIC. sizeof(BOM_UTF8) - 1 может быть использован для получения его длины в байтах.

bytes_cmp_utf8

Сравнивает последовательность символов (хранящихся как октеты) в Uid_t_f, blen с последовательностью символов (хранящихся как UTF-8) в u, ulen.

Возвращает 0, если они равны, -1 или -2, если первая строка меньше второй строки, +1 или +2, если первая строка больше второй строки.

-1 или +1 возвращается, если более короткая строка была идентична началу более длинной строки. -2 или +2 возвращается, если были различия между символами внутри строк.

int  bytes_cmp_utf8(const U8 *b, STRLEN blen, const U8 *u,
                    STRLEN ulen)
bytes_from_utf8

ПРИМЕЧАНИЕ: bytes_from_utf8 является экспериментальным и может быть изменен или удален без предварительного уведомления.

Преобразует потенциально закодированную в UTF-8 строку s длины *lenp в кодировку байтов по умолчанию. На входе, булево значение *is_utf8p указывает, закодирована ли s в UTF-8.

В отличие от "utf8_to_bytes", но подобно "bytes_to_utf8", эта функция не разрушает входную строку.

Не делает ничего, если *is_utf8p равно 0 или если в строке есть символы, не представимые в кодировке байтов по умолчанию. В этих случаях *is_utf8p и *lenp остаются неизменными, а возвращаемое значение — исходное s.

В противном случае *is_utf8p устанавливается в 0, и возвращается указатель на новую строку, содержащую пониженную копию s, а её длина возвращается в *lenp, обновлённая. Новая строка завершается NUL. Вызывающая сторона отвечает за освобождение памяти, используемой этой строкой.

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

U8 *  bytes_from_utf8(const U8 *s, STRLEN *lenp, bool *is_utf8p)
bytes_to_utf8

ПРИМЕЧАНИЕ: bytes_to_utf8 является экспериментальным и может быть изменен или удален без предварительного уведомления.

Преобразует строку s длиной *lenp байт из кодировки по умолчанию в UTF-8. Возвращает указатель на новую строку и устанавливает *lenp для отражения новой длины в байтах. Вызывающая сторона отвечает за освобождение памяти, используемой этой строкой.

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

Символ NUL будет записан после конца строки.

Если вы хотите преобразовать в UTF-8 из кодировок, отличных от кодировки по умолчанию (Latin1 или EBCDIC), см. "sv_recode_to_utf8"().

U8 *  bytes_to_utf8(const U8 *s, STRLEN *lenp)
DO_UTF8

Возвращает булево значение, указывающее, рассматривается ли PV в sv как закодированный в UTF-8.

Вы должны использовать это после вызова SvPV() или одной из его разновидностей, в случае, если какой-либо вызов перегрузки строк обновит внутренний флаг кодировки UTF-8.

bool  DO_UTF8(SV* sv)
foldEQ_utf8

Возвращает true, если начальные части строк s1 и s2 (любая или обе из которых могут быть в UTF-8) одинаковы с учётом регистра; в противном случае возвращает false. Расстояние в строках, которое нужно сравнить, определяется другими входными параметрами.

Если u1 равно true, строка s1 предполагается закодированной в UTF-8; в противном случае она предполагается закодированной в кодировке байтов по умолчанию. Аналогично для u2 относительно s2.

Если длина байтов l1 отлична от нуля, она указывает, насколько глубоко в s1 нужно искать равенство с учётом регистра. Другими словами, s1+l1 будет использоваться как цель для достижения. Сканирование не считается совпадением, если цель не достигнута, и сканирование не будет продолжаться за этой целью. Аналогично для l2 относительно s2.

Если pe1 не равно нулю и указатель, на который он указывает, не равен нулю, этот указатель считается конечным указателем, расположенным в 1 байт за максимальной точкой в s1, за которую сканирование не будет продолжаться ни при каких обстоятельствах. (Эта функция предполагает, что входные строки UTF-8 не содержат ошибок; повреждённые данные могут привести к чтению за пределами pe1).

Это означает, что если и l1, и pe1 указаны, и pe1 меньше, чем s1+l1, совпадение никогда не произойдёт, потому что оно никогда не сможет достичь своей цели (и фактически этому препятствуют условия).

Аналогично для pe2 относительно s2.

По крайней мере, одна из переменных s1 и s2 должна иметь цель (по крайней мере, одна из l1 и l2 должна быть отлична от нуля), и если обе имеют цели, обе должны быть достигнуты для успешного совпадения. Кроме того, если склад символа содержит несколько символов, все они должны быть сопоставлены (см. ссылку на tr21 ниже для 'folding').

При успешном совпадении, если pe1 не равно нулю, оно будет установлено в начало следующего символа s1 за тем, что было сопоставлено. Аналогично для pe2 и s2.

Для сравнения с учётом регистра используется «свертывание регистра» Unicode вместо преобразования символов в верхний или нижний регистр, см. https://www.unicode.org/reports/tr21/ (Преобразования регистра).

I32  foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1,
                 const char *s2, char **pe2, UV l2, bool u2)
is_ascii_string

Это вводящее в заблуждение синоним для "is_utf8_invariant_string". На платформах ASCII-подобного типа имя не вводит в заблуждение: символы ASCII-диапазона точно соответствуют инвариантам UTF-8. Но на машинах EBCDIC инвариантов больше, чем просто символов ASCII, поэтому is_utf8_invariant_string предпочтительнее.

bool  is_ascii_string(const U8 * const s, STRLEN len)
isC9_STRICT_UTF8_CHAR

Получает ненулевое значение, если первые несколько байтов строки, начиная с s и не выходя за пределы e - 1, являются корректными байтами UTF-8, представляющими некоторый код Unicode без суррогатов; в противном случае получает 0. Если ненулевое, значение указывает, сколько байтов, начиная с s, составляют представление кода символа. Любые оставшиеся байты до e, но после тех, которые нужны для формирования первого кода символа в s, не проверяются.

Наибольший допустимый код символа — максимальное значение Unicode 0x10FFFF. Это отличается от "isSTRICT_UTF8_CHAR" только тем, что оно принимает коды символов, которые не являются символами. Это соответствует Unicode Corrigendum #9, в котором говорилось, что коды символов, которые не являются символами, просто не поощряются, а не полностью запрещены при открытом обмене. См. "Коды символов, не являющихся символами" в perlunicode.

Используйте "isUTF8_CHAR" для проверки расширенного UTF-8 Perl; и "isUTF8_CHAR_flags" для более настраиваемого определения.

Используйте "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen" для проверки целых строк.

Size_t  isC9_STRICT_UTF8_CHAR(const U8 * const s0,
                              const U8 * const e)
is_c9strict_utf8_string

Возвращает ИСТИНА, если первые len байты строки s образуют корректную строку UTF-8, соответствующую Unicode Corrigendum #9; в противном случае возвращает ЛОЖЬ. Если len равно 0, оно будет вычислено с использованием strlen(s) (что означает, что если вы используете этот параметр, то s не может содержать вложенных символов NUL и должен иметь завершающий байт NUL). Обратите внимание, что все символы ASCII составляют «корректную строку UTF-8».

Эта функция возвращает ЛОЖЬ для строк, содержащих коды символов выше максимального значения Unicode 0x10FFFF или суррогатные коды, но принимает коды символов, которые не являются символами, согласно Поправке #9.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string", "is_utf8_string_flags", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool  is_c9strict_utf8_string(const U8 *s, STRLEN len)
is_c9strict_utf8_string_loc

Как и "is_c9strict_utf8_string", но хранит расположение ошибки (в случае ошибки «utf8») или расположение s+len (в случае успеха «utf8») в указателе ep.

См. также "is_c9strict_utf8_string_loclen".

bool  is_c9strict_utf8_string_loc(const U8 *s, STRLEN len,
                                  const U8 **ep)
is_c9strict_utf8_string_loclen

Как и "is_c9strict_utf8_string", но хранит расположение ошибки (в случае ошибки «utf8») или расположение s+len (в случае успеха «utf8») в указателе ep, и количество закодированных в UTF-8 символов в указателе el.

См. также "is_c9strict_utf8_string_loc".

bool  is_c9strict_utf8_string_loclen(const U8 *s, STRLEN len,
                                     const U8 **ep, STRLEN *el)
END_OF_DOCUMENT_MARKER
is_invariant_string

Это немного вводящее в заблуждение синоним для "is_utf8_invariant_string". is_utf8_invariant_string предпочтительнее, так как указывает условия, при которых строка инвариантна.

bool  is_invariant_string(const U8 * const s, STRLEN len)
isSTRICT_UTF8_CHAR

Возвращает ненулевое значение, если первые несколько байтов строки, начиная с s и не дальше, чем e - 1, являются правильно сформированными UTF-8, представляющими некоторую точку кода Юникода, полностью приемлемую для открытого обмена между всеми приложениями; в противном случае возвращает 0. Если ненулевое, значение показывает, сколько байтов, начиная с s, составляют представление точки кода. Любые байты, оставшиеся до e, но за пределами необходимых для формирования первой точки кода в s, не проверяются.

Наибольшая допустимая точка кода — максимальное значение Юникода 0x10FFFF, и она не должна быть суррогатной или недопустимой точкой кода. Таким образом, это исключает любые точки кода из расширенного UTF-8 Perl.

Это используется для эффективного определения, являются ли следующие несколько байтов в s законным Юникод-приемлемым UTF-8 для одного символа.

Используйте "isC9_STRICT_UTF8_CHAR" для использования определения допустимых точек кода Исправления Юникода #9; "isUTF8_CHAR" для проверки расширенного UTF-8 Perl; и "isUTF8_CHAR_flags" для более настраиваемого определения.

Используйте "is_strict_utf8_string", "is_strict_utf8_string_loc", и "is_strict_utf8_string_loclen" для проверки целых строк.

Size_t  isSTRICT_UTF8_CHAR(const U8 * const s0,
                           const U8 * const e)
is_strict_utf8_string

Возвращает TRUE, если первые len байта строки s образуют допустимую UTF-8-кодированную строку, полностью взаимозаменяемую любым приложением, использующим правила Юникода; в противном случае возвращает FALSE. Если len равно 0, оно будет вычислено с использованием strlen(s) (что означает, что если вы используете этот вариант, s не может содержать встроенных NUL символов и должна иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «допустимую UTF-8-строку».

Эта функция возвращает FALSE для строк, содержащих любые точки кода, превышающие максимальное значение Юникода 0x10FFFF, суррогатные точки кода или недопустимые точки кода.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string", "is_utf8_string_flags", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool  is_strict_utf8_string(const U8 *s, STRLEN len)
is_strict_utf8_string_loc

Подобно "is_strict_utf8_string", но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе ep.

См. также "is_strict_utf8_string_loclen".

bool  is_strict_utf8_string_loc(const U8 *s, STRLEN len,
                                const U8 **ep)
is_strict_utf8_string_loclen

Подобно "is_strict_utf8_string", но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе ep, и количество UTF-8 кодированных символов в указателе el.

См. также "is_strict_utf8_string_loc".

bool  is_strict_utf8_string_loclen(const U8 *s, STRLEN len,
                                   const U8 **ep, STRLEN *el)
isUTF8_CHAR

Возвращает ненулевое значение, если первые несколько байтов строки, начиная с s и не дальше, чем e - 1, являются правильно сформированными UTF-8, расширенными Perl, представляющими некоторую точку кода; в противном случае возвращает 0. Если ненулевое, значение показывает, сколько байтов, начиная с s, составляют представление точки кода. Любые байты, оставшиеся до e, но за пределами необходимых для формирования первой точки кода в s, не проверяются.

Точка кода может быть любой, которая поместится в IV на этом компьютере, используя расширение Perl к официальному UTF-8 для представления точек кода, больших, чем максимальное значение Юникода 0x10FFFF. Это означает, что эта макрокоманда используется для эффективного определения, являются ли следующие несколько байтов в s законным UTF-8 для одного символа.

Используйте "isSTRICT_UTF8_CHAR" для ограничения допустимых точек кода только теми, которые определены Юникодом как полностью взаимозаменяемые между приложениями; "isC9_STRICT_UTF8_CHAR" для использования определения допустимых точек кода Исправления Юникода #9; и "isUTF8_CHAR_flags" для более настраиваемого определения.

Используйте "is_utf8_string", "is_utf8_string_loc", и "is_utf8_string_loclen" для проверки целых строк.

Также обратите внимание, что UTF-8 «инвариантный» символ (т. е. ASCII на машинах, не являющихся EBCDIC) является допустимым UTF-8 символом.

Size_t  isUTF8_CHAR(const U8 * const s0, const U8 * const e)
is_utf8_char_buf

Это идентично макрокоманде "isUTF8_CHAR" в perlapi.

STRLEN  is_utf8_char_buf(const U8 *buf, const U8 *buf_end)
isUTF8_CHAR_flags

Возвращает ненулевое значение, если первые несколько байтов строки, начиная с s и не дальше, чем e - 1, являются правильно сформированными UTF-8, расширенными Perl, представляющими некоторую точку кода, подлежащие ограничениям, указанным в flags; в противном случае возвращает 0. Если ненулевое, значение показывает, сколько байтов, начиная с s, составляют представление точки кода. Любые байты, оставшиеся до e, но за пределами необходимых для формирования первой точки кода в s, не проверяются.

Если flags равно 0, это даёт те же результаты, что и "isUTF8_CHAR"; если flags равно UTF8_DISALLOW_ILLEGAL_INTERCHANGE, это даёт те же результаты, что и "isSTRICT_UTF8_CHAR"; и если flags равно UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE, это даёт те же результаты, что и "isC9_STRICT_UTF8_CHAR". В противном случае flags может быть любой комбинацией флагов UTF8_DISALLOW_foo, понятых "utf8n_to_uvchr", с теми же значениями.

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

Используйте "is_utf8_string_flags", "is_utf8_string_loc_flags" и "is_utf8_string_loclen_flags" для проверки целых строк.

Size_t  isUTF8_CHAR_flags(const U8 * const s0, const U8 * const e,
                          const U32 flags)
is_utf8_fixed_width_buf_flags

Возвращает TRUE, если фиксированный буфер, начиная с s с длиной len, полностью является допустимым UTF-8, с учётом ограничений, указанных в flags; в противном случае возвращает FALSE.

Если flags равно 0, любой правильно сформированный UTF-8, расширенный Perl, принимается без ограничений. Если последние несколько байтов буфера не образуют полную точку кода, это всё равно вернёт TRUE, при условии, что "is_utf8_valid_partial_char_flags" вернёт TRUE для них.

Если flags ненулевое, оно может быть любой комбинацией флагов UTF8_DISALLOW_foo, принятых "utf8n_to_uvchr", и с теми же значениями.

Эта функция отличается от "is_utf8_string_flags" только тем, что последняя возвращает FALSE, если последние несколько байтов строки не образуют полную точку кода.

bool  is_utf8_fixed_width_buf_flags(const U8 * const s,
                                    STRLEN len, const U32 flags)
is_utf8_fixed_width_buf_loc_flags

Подобно "is_utf8_fixed_width_buf_flags", но сохраняет местоположение ошибки в указателе ep. Если функция возвращает TRUE, *ep будет указывать на начало любого частичного символа в конце буфера; если частичный символ отсутствует, *ep будет содержать s+len.

См. также "is_utf8_fixed_width_buf_loclen_flags".

bool  is_utf8_fixed_width_buf_loc_flags(const U8 * const s,
                                        STRLEN len, const U8 **ep,
                                        const U32 flags)
is_utf8_fixed_width_buf_loclen_flags

Подобно "is_utf8_fixed_width_buf_loc_flags", но сохраняет количество полных, допустимых символов в указателе el.

bool  is_utf8_fixed_width_buf_loclen_flags(const U8 * const s,
                                           STRLEN len,
                                           const U8 **ep,
                                           STRLEN *el,
                                           const U32 flags)
is_utf8_invariant_string

Возвращает TRUE, если первые len байты строки s одинаковы независимо от UTF-8 кодирования строки (или UTF-EBCDIC кодирования на машинах EBCDIC); в противном случае возвращает FALSE. То есть, возвращает TRUE, если они UTF-8 инвариантны. На машинах ASCII, все символы ASCII и только они соответствуют этому определению. На машинах EBCDIC символы в диапазоне ASCII также инвариантны, но так же, как и управляющие символы C1.

Если len равно 0, оно будет вычислено с использованием strlen(s), (что означает, что если вы используете этот вариант, s не может содержать встроенных NUL символов и должна иметь завершающий NUL байт).

См. также "is_utf8_string", "is_utf8_string_flags", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool  is_utf8_invariant_string(const U8 * const s, STRLEN len)
is_utf8_invariant_string_loc

Подобно "is_utf8_invariant_string", но при ошибке сохраняет местоположение первого UTF-8 неинвариантного символа в указателе ep; если все символы UTF-8 инвариантны, эта функция не изменяет содержимое *ep.

bool  is_utf8_invariant_string_loc(const U8 * const s, STRLEN len,
                                   const U8 **ep)
is_utf8_string

Возвращает TRUE, если первые len байты строки s образуют допустимую строку Perl-расширенного UTF-8; в противном случае возвращает FALSE. Если len равно 0, оно будет вычислено с использованием strlen(s) (что означает, что если вы используете этот вариант, s не может содержать встроенных NUL символов и должна иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «допустимую UTF-8 строку».

Эта функция считает расширенный UTF-8 Perl допустимым. Это означает, что точки кода, превышающие Юникод, суррогаты и недопустимые точки кода считаются допустимыми этой функцией. Используйте "is_strict_utf8_string", "is_c9strict_utf8_string", или "is_utf8_string_flags" для ограничения допустимых точек кода.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string_loc", "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags",

bool  is_utf8_string(const U8 *s, STRLEN len)
is_utf8_string_flags

Возвращает TRUE, если первые len байты строки s образуют корректную строку UTF-8, с учётом ограничений, наложенных flags; в противном случае возвращает FALSE. Если len равно 0, оно будет вычислено с использованием strlen(s) (что означает, что если вы используете этот параметр, s не может содержать встроенные NUL символы и должна иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют 'корректную строку UTF-8'.

Если flags равно 0, это даёт те же результаты, что и "is_utf8_string"; если flags равно UTF8_DISALLOW_ILLEGAL_INTERCHANGE, это даёт те же результаты, что и "is_strict_utf8_string"; а если flags равно UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE, это даёт те же результаты, что и "is_c9strict_utf8_string". В противном случае flags может быть любой комбинацией UTF8_DISALLOW_foo флагов, понятных "utf8n_to_uvchr", со схожими значениями.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool  is_utf8_string_flags(const U8 *s, STRLEN len,
                           const U32 flags)
is_utf8_string_loc

Подобно "is_utf8_string", но сохраняет местоположение ошибки (в случае "ошибки UTF-8") или местоположение s + len (в случае "успеха UTF-8") в указателе ep.

См. также "is_utf8_string_loclen".

bool  is_utf8_string_loc(const U8 *s, const STRLEN len,
                         const U8 **ep)
is_utf8_string_loc_flags

Подобно "is_utf8_string_flags", но сохраняет местоположение ошибки (в случае "ошибки UTF-8") или местоположение s + len (в случае "успеха UTF-8") в указателе ep.

См. также "is_utf8_string_loclen_flags".

bool  is_utf8_string_loc_flags(const U8 *s, STRLEN len,
                               const U8 **ep, const U32 flags)
is_utf8_string_loclen

Подобно "is_utf8_string", но сохраняет местоположение ошибки (в случае "ошибки UTF-8") или местоположение s + len (в случае "успеха UTF-8") в указателе ep, и количество кодированных символов UTF-8 в указателе el.

См. также "is_utf8_string_loc".

bool  is_utf8_string_loclen(const U8 *s, STRLEN len,
                            const U8 **ep, STRLEN *el)
is_utf8_string_loclen_flags

Подобно "is_utf8_string_flags", но сохраняет местоположение ошибки (в случае "ошибки UTF-8") или местоположение s + len (в случае "успеха UTF-8") в указателе ep, и количество кодированных символов UTF-8 в указателе el.

См. также "is_utf8_string_loc_flags".

bool  is_utf8_string_loclen_flags(const U8 *s, STRLEN len,
                                  const U8 **ep, STRLEN *el,
                                  const U32 flags)
is_utf8_valid_partial_char

Возвращает 0, если последовательность байтов, начиная с s и не выходя за пределы e - 1, представляет собой кодировку UTF-8, как она расширена в Perl, для одного или нескольких кодовых точек. В противном случае возвращает 1, если существует по крайней мере одна непустая последовательность байтов, которая, будучи добавленной к последовательности s, начиная с позиции e, делает всю последовательность корректной UTF-8-строкой некоторой кодовой точки; в противном случае возвращает 0.

Другими словами, это возвращает TRUE, если s указывает на частичный UTF-8 кодированный символ.

Это полезно, когда тестируется буфер фиксированной длины на корректность UTF-8, но последние несколько байтов в нём не образуют целого символа; то есть, он разделён где-то посредине представления последней кодовой точки в UTF-8. (Предполагается, что когда буфер обновляется следующим фрагментом данных, новые первые байты завершат частичную кодовую точку.) Эта функция используется для проверки того, что последние байты в текущем буфере на самом деле являются законным началом некоторой кодовой точки, так что если этого нет, ошибка может быть сигнализирована, не дожидаясь следующего чтения.

bool  is_utf8_valid_partial_char(const U8 * const s0,
                                 const U8 * const e)
is_utf8_valid_partial_char_flags

Подобно "is_utf8_valid_partial_char", она возвращает булево значение, указывающее, является ли ввод корректным частичным символом UTF-8, но принимает дополнительный параметр, flags, который может дополнительно ограничить допустимые кодовые точки.

Если flags равно 0, это поведение идентично "is_utf8_valid_partial_char". В противном случае flags может быть любой комбинацией UTF8_DISALLOW_foo флагов, принятых "utf8n_to_uvchr". Если существует последовательность байтов, которая может завершить частичный символ ввода таким образом, что образуется допустимый символ, функция возвращает TRUE; в противном случае FALSE. Кодовые точки, не являющиеся символами, не могут быть определены на основе частичного ввода символа. Но многие другие возможные исключённые типы могут быть определены только по первому или двум байтам.

bool  is_utf8_valid_partial_char_flags(const U8 * const s0,
                                       const U8 * const e,
                                       const U32 flags)
LATIN1_TO_NATIVE

Возвращает эквивалент кодовой точки Latin-1 входного значения (включая ASCII и управляющие символы), заданной ch. Таким образом, LATIN1_TO_NATIVE(66) на платформах EBCDIC возвращает 194. Каждый из них представляет символ "B" на соответствующих платформах. На платформах ASCII преобразование не требуется, поэтому этот макрос просто расширяется до своего входного значения, не добавляя временных или пространственных требований к реализации.

Для преобразования кодовых точек, потенциально больших, чем может уместиться в символе, используйте "UNI_TO_NATIVE".

U8  LATIN1_TO_NATIVE(U8 ch)
NATIVE_TO_LATIN1

Возвращает эквивалент кодовой точки Latin-1 (включая ASCII и управляющие символы) для входной кодовой точки, заданной ch. Таким образом, NATIVE_TO_LATIN1(193) на платформах EBCDIC возвращает 65. Каждый из них представляет символ "A" на соответствующих платформах. На платформах ASCII преобразование не требуется, поэтому этот макрос просто расширяется до своего входного значения, не добавляя временных или пространственных требований к реализации.

Для преобразования кодовых точек, потенциально больших, чем может уместиться в символе, используйте "NATIVE_TO_UNI".

U8  NATIVE_TO_LATIN1(U8 ch)
NATIVE_TO_UNI

Возвращает Unicode эквивалент входной кодовой точки, заданной ch. Таким образом, NATIVE_TO_UNI(195) на платформах EBCDIC возвращает 67. Каждый из них представляет символ "C" на соответствующих платформах. На платформах ASCII преобразование не требуется, поэтому этот макрос просто расширяется до своего входного значения, не добавляя временных или пространственных требований к реализации.

UV  NATIVE_TO_UNI(UV ch)
pv_uni_display

Создаёт в скаляре dsv отображаемую версию строки UTF-8 spv, длиной len, при этом отображаемая версия не превышает pvlim байтов (если больше, остальная часть усекается и добавляется "...").

Аргумент flags может иметь UNI_DISPLAY_ISPRINT для отображения отображаемых символов как таковых, UNI_DISPLAY_BACKSLASH для отображения \\[nrfta\\] в виде обратных слешей (как "\n") (UNI_DISPLAY_BACKSLASH предпочтительнее UNI_DISPLAY_ISPRINT для "\\"). UNI_DISPLAY_QQ (и его псевдоним UNI_DISPLAY_REGEX) имеют оба UNI_DISPLAY_BACKSLASH и UNI_DISPLAY_ISPRINT включёнными.

Кроме того, теперь есть UNI_DISPLAY_BACKSPACE, что позволяет использовать \b для обратного удаления, но только когда UNI_DISPLAY_BACKSLASH также установлено.

Возвращается указатель на PV отображаемой строки.

См. также "sv_uni_display".

char *  pv_uni_display(SV *dsv, const U8 *spv, STRLEN len,
                       STRLEN pvlim, UV flags)
REPLACEMENT_CHARACTER_UTF8

Это макрос, который вычисляется как строковая константа байтов UTF-8, определяющих символ ЗАМЕЩЕНИЯ Юникода (U+FFFD) для платформы, на которой скомпилирован Perl. Это позволяет коду использовать мнемонику для этого символа, которая работает как на платформах ASCII, так и EBCDIC. sizeof(REPLACEMENT_CHARACTER_UTF8) - 1 может использоваться для получения его длины в байтах.

sv_cat_decode

encoding предполагается, что является объектом Encode, PV ssv предполагается, что представляет собой байты в этой кодировке, и декодирование ввода начинается с позиции, на которую указывает (PV + *offset). dsv будет конкатенирован с декодированной строкой UTF-8 из ssv. Декодирование завершится, когда в результирующей строке встретится tstr или ввод закончится на PV ssv. Значение, на которое указывает offset, будет изменено на последнюю позицию ввода в ssv.

Возвращает TRUE, если разделитель был найден, иначе FALSE.

bool  sv_cat_decode(SV *dsv, SV *encoding, SV *ssv, int *offset,
                    char *tstr, int tlen)
sv_recode_to_utf8

encoding предполагается, что является объектом Encode, на вход PV sv предполагается, что представляет собой байты в указанной кодировке, и sv будет преобразовано в Unicode (и UTF-8).

Если sv уже является UTF-8 (или если это не POK), или если encoding не является ссылкой, ничего не делается с sv. Если encoding не является объектом кодировки Encode::XS, произойдут плохие вещи. (См. encoding и Encode.)

Возвращается PV sv.

char *  sv_recode_to_utf8(SV *sv, SV *encoding)
sv_uni_display

Создаёт в скаляре dsv отображаемую версию скаляра sv, при этом отображаемая версия не превышает pvlim байтов (если больше, остальная часть усекается и добавляется "...").

Аргумент flags такой же, как в "pv_uni_display"().

Возвращается указатель на PV отображаемой строки.

char *  sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
UNICODE_IS_NONCHAR

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

bool  UNICODE_IS_NONCHAR(const UV uv)
UNICODE_IS_REPLACEMENT

Возвращает булево значение, указывающее, является ли uv символом ЗАМЕЩЕНИЯ Юникода.

bool  UNICODE_IS_REPLACEMENT(const UV uv)
UNICODE_IS_SUPER

Возвращает булево значение, указывающее, превышает ли uv максимальную допустимую кодовую точку Юникода U+10FFFF.

bool  UNICODE_IS_SUPER(const UV uv)
UNICODE_IS_SURROGATE

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

bool  UNICODE_IS_SURROGATE(const UV uv)
END_OF_DOCUMENT_MARKER
UNICODE_REPLACEMENT

Возвращает 0xFFFD, код точки Unicode ЗАМЕЩАЮЩИЙ СИМВОЛ

UNI_TO_NATIVE

Возвращает родственный эквивалент входной точки кода Юникода, заданной ch. Таким образом, UNI_TO_NATIVE(68) на платформах EBCDIC возвращает 196. Каждый из них представляет символ "D" на соответствующих платформах. На платформах ASCII преобразование не требуется, поэтому этот макрос просто расширяется до своего входного значения, не накладывая никаких временных или пространственных требований на реализацию.

UV  UNI_TO_NATIVE(UV ch)
UTF8_CHK_SKIP

Это более безопасная версия "UTF8SKIP", но все еще не так безопасна, как "UTF8_SAFE_SKIP". Эта версия не слепо предполагает, что входная строка, на которую указывает s, имеет правильный формат, но проверяет, что нет символа NUL перед ожидаемым концом следующего символа в s. Длина UTF8_CHK_SKIP заканчивается непосредственно перед любым таким NUL.

Perl имеет тенденцию добавлять NUL, как страховочную меру, после конца строк в SV, поэтому, вероятно, использование этого макроса предотвратит непреднамеренное чтение за пределы буфера ввода, даже если он имеет неправильный формат UTF-8.

Этот макрос предназначен для использования модулями XS, где входные данные могут быть неправильного формата, и перестройка для использования более безопасного "UTF8_SAFE_SKIP" нецелесообразна, например, при взаимодействии с библиотекой C.

STRLEN  UTF8_CHK_SKIP(char* s)
utf8_distance

Возвращает количество символов UTF-8 между указателями UTF-8 a и b.

ПРЕДУПРЕЖДЕНИЕ: используйте только если вы *точно* знаете, что указатели находятся внутри одного и того же буфера UTF-8.

IV  utf8_distance(const U8 *a, const U8 *b)
utf8_hop

Возвращает указатель UTF-8 s, смещенный на off символов, либо вперёд (если off положительно), либо назад (если отрицательно). s не обязательно должен указывать на стартовый байт символа. Если это не так, один счёт off будет использован, чтобы перейти к началу следующего символа для переходов вперёд, и к началу текущего символа для обратных переходов.

ПРЕДУПРЕЖДЕНИЕ: Предпочитайте "utf8_hop_safe" этой функции.

НЕ используйте эту функцию, если вы точно не знаете, что off находится в данных UTF-8, на которые указывает s, и что при входе s выровнен на первом байте символа или сразу после последнего байта символа.

U8 *  utf8_hop(const U8 *s, SSize_t off)
utf8_hop_back

Возвращает указатель UTF-8 s, смещенный на максимально off символов назад. s не обязательно должен указывать на стартовый байт символа. Если это не так, один счёт off будет использован, чтобы перейти к этому началу.

off должно быть неположительным.

s должен быть после или равен start.

При движении назад не будет перемещаться перед start.

Не превысит этого предела, даже если строка не является валидным UTF-8.

U8 *  utf8_hop_back(const U8 *s, SSize_t off, const U8 *start)
utf8_hop_forward

Возвращает указатель UTF-8 s смещённый на максимально off символов вперёд. s не обязательно должен указывать на стартовый байт символа. Если это не так, один счёт off будет использован, чтобы перейти к началу следующего символа.

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

s должно быть перед или равно end.

При движении вперёд не будет перемещаться за пределы end.

Не превысит этого предела, даже если строка не является валидным UTF-8.

U8 *  utf8_hop_forward(const U8 *s, SSize_t off, const U8 *end)
utf8_hop_safe

Возвращает указатель UTF-8 s смещенный на максимально off символов, вперёд или назад. s не обязательно должен указывать на стартовый байт символа. Если это не так, один счёт off будет использован, чтобы перейти к началу следующего символа для переходов вперёд, и к началу текущего символа для обратных переходов.

При движении назад не будет перемещаться перед start.

При движении вперёд не будет перемещаться за пределы end.

Не превысит эти пределы, даже если строка не является валидным UTF-8.

U8 *  utf8_hop_safe(const U8 *s, SSize_t off, const U8 *start,
                    const U8 *end)
UTF8_IS_INVARIANT

Возвращает 1, если байт c представляет тот же символ при кодировании в UTF-8, что и без кодирования; иначе возвращает 0. Инвариантные символы UTF-8 могут копироваться как есть при преобразовании в/из UTF-8, что экономит время.

Несмотря на название, этот макрос даёт правильный результат, если входная строка, из которой получен c, не закодирована в UTF-8.

См. "UVCHR_IS_INVARIANT" для проверки, является ли UV инвариантной.

bool  UTF8_IS_INVARIANT(char c)
UTF8_IS_NONCHAR

Возвращает ненулевое значение, если первые несколько байтов строки, начиная с s и не далее чем e - 1, являются валидным UTF-8, представляющим одну из точек кода Unicode, не являющуюся символом; иначе возвращает 0. Если ненулевое значение, то оно показывает количество байтов, начиная с s, составляющих представление точки кода.

bool  UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
UTF8_IS_REPLACEMENT

Возвращает ненулевое значение, если первые несколько байтов строки, начиная с s и не далее чем e - 1, являются валидным UTF-8, представляющим ЗАМЕЩАЮЩИЙ СИМВОЛ Unicode; иначе возвращает 0. Если ненулевое значение, то оно показывает количество байтов, начиная с s составляющих представление точки кода.

bool  UTF8_IS_REPLACEMENT(const U8 *s, const U8 *e)
UTF8_IS_SUPER

Напомним, что Perl распознает расширение UTF-8, которое может кодировать точки кода, превышающие определённые Unicode, которые находятся в диапазоне 0..0x10FFFF.

Этот макрос возвращает ненулевое значение, если первые несколько байтов строки, начиная с s и не далее чем e - 1, относятся к этому расширению UTF-8; иначе возвращает 0. Если ненулевое значение, то результат показывает сколько байтов, начиная с s составляют представление точки кода.

0 возвращается, если байты не имеют правильного формата расширенного UTF-8 или если они представляют точку кода, которая не может поместиться в UV на текущей платформе. Поэтому этот макрос может давать разные результаты при запуске на 64-битной машине, чем на 32-битной.

Обратите внимание, что в Perl запрещено иметь точки кода, превышающие размер IV на текущей машине; и в Unicode запрещено иметь любые точки кода, которые этот макрос находит.

bool  UTF8_IS_SUPER(const U8 *s, const U8 *e)
UTF8_IS_SURROGATE

Возвращает ненулевое значение, если первые несколько байтов строки, начиная с s и не далее чем e - 1, являются валидным UTF-8, представляющим одну из замещающих точек кода Unicode; иначе возвращает 0. Если ненулевое значение, то оно показывает количество байтов, начиная с s составляющих представление точки кода.

bool  UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
utf8_length

Возвращает количество символов в последовательности байтов UTF-8, начинающейся с s и заканчивающейся байтом, предшествующим e. Если <s> и <e> указывают на одно и то же место, возвращает 0 без вывода предупреждения.

Если e < s или если сканирование закончит анализ после e, генерируется предупреждение UTF8 и возвращается количество допустимых символов.

STRLEN  utf8_length(const U8 *s0, const U8 *e)
UTF8_MAXBYTES

Максимальная ширина одного символа UTF-8, в байтах.

ПРИМЕЧАНИЕ: Строго говоря, UTF-8 в Perl не должен называться UTF-8, так как UTF-8 – это кодировка Юникода, а верхний предел Юникода 0x10FFFF может быть выражен 4 байтами. Тем не менее, Perl рассматривает UTF-8 как способ кодирования целых неотрицательных чисел в двоичном формате, даже тех, которые превышают Юникод.

UTF8_MAXBYTES_CASE

Максимальное количество байтов UTF-8, которые один символ Юникода может преобразовать в верхний/нижний регистр/заголовок/свернуть.

utf8ness_t

Этот typedef используется несколькими базовыми функциями, возвращающими строковые PV, для указания UTF-8-ности этих строк.

(Если вы пишете новую функцию, вы, вероятно, должны вместо этого вернуть PV в SV с правильно установленным флагом UTF-8 SV, а не использовать этот механизм.)

Возможные значения, которые он может принимать:

UTF8NESS_YES

Это означает, что строка определённо должна обрабатываться как последовательность символов, закодированных в UTF-8.

Большинство кодов, которые нужно обработать, должны быть следующего вида:

if (utf8ness_flag == UTF8NESS_YES) {
    treat as utf8;  // like turning on an SV UTF-8 flag
}
UTF8NESS_NO

Это означает, что строка определённо должна обрабатываться как последовательность байтов, не закодированных как UTF-8.

UTF8NESS_IMMATERIAL

Это означает, что строка может быть одинаково обработана как байты, или как символы UTF-8; используйте тот способ, который вам нужен. Это происходит, когда строка состоит только из символов, которые имеют одинаковое представление, закодированные в UTF-8 или нет.

UTF8NESS_UNKNOWN

Это означает, что неизвестно, как должна быть обработана строка. Ни одна функция ядра никогда не вернёт это значение вызывающей стороне, не являющейся функцией ядра. Вместо этого оно используется вызывающей стороной для инициализации переменной недопустимым значением. Типичный вызов будет выглядеть так:

utf8ness_t string_is_utf8 = UTF8NESS_UNKNOWN
const char * string = foo(arg1, arg2, ..., &string_is_utf8);
if (string_is_utf8 == UTF8NESS_YES) {
   do something for UTF-8;
}

Между значениями перечисления сохраняются следующие отношения:

0 <= enum value <= UTF8NESS_IMMATERIAL

строка может обрабатываться в коде как не UTF-8

UTF8NESS_IMMATERIAL <= <enum value

строка может обрабатываться в коде как закодированная в UTF-8

utf8n_to_uvchr

ЭТУ ФУНКЦИЮ СЛЕДУЕТ ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛИЗИРОВАННЫХ СЛУЧАЯХ. Большинство кодов должно использовать "utf8_to_uvchr_buf"() вместо прямого вызова.

Базовая процедура декодирования UTF-8. Возвращает значение кодовой точки первого символа в строке s, которая предполагается в кодировке UTF-8 (или UTF-EBCDIC), и не длиннее чем curlen байт; *retlen (если retlen не равно NULL) будет установлено в длину этого символа в байтах.

Значение flags определяет поведение при том, что s не указывает на правильно сформированный символ UTF-8. Если flags равно 0, обнаружение неверной последовательности приводит к возвращению нуля и *retlen устанавливается так, что (s + *retlen) является следующей возможной позицией в s, которая может начинаться с правильно сформированного символа. Также, если предупреждения UTF-8 не отключены лексически, генерируется предупреждение. Некоторые последовательности ввода UTF-8 могут содержать несколько ошибок. Данная функция пытается найти каждую возможную ошибку в каждом вызове, поэтому могут быть сгенерированы несколько предупреждений для одной и той же последовательности.

Различные флаги ALLOW могут быть установлены в flags для разрешения (и отсутствия предупреждений) отдельных типов ошибок, таких как слишком длинная последовательность (то есть, когда существует более короткая последовательность, которая может выразить ту же кодовую точку; слишком длинные последовательности прямо запрещены в стандарте UTF-8 из-за потенциальных проблем безопасности). Другой пример ошибки — первый байт символа не является допустимым первым байтом. Список таких флагов см. в utf8.h. Даже если разрешено, эта функция обычно возвращает заменяющий символ Unicode при обнаружении ошибки. Существуют флаги в utf8.h для переопределения этого поведения для ошибок с длинными последовательностями, но не делайте этого, кроме очень специализированных целей.

Флаг UTF8_CHECK_ONLY переопределяет поведение при обнаружении ошибки, не разрешённой другими флагами. Если этот флаг установлен, процедура предполагает, что вызывающий объект сгенерирует предупреждение, и эта функция безмолвно установит retlen в -1 (приведено к типу STRLEN) и вернёт ноль.

Обратите внимание, что этот API требует разграничения успешного декодирования символа NUL, и ошибочного возврата (если не установлен флаг UTF8_CHECK_ONLY), поскольку в обоих случаях возвращается 0, и, в зависимости от ошибки, retlen может быть установлено в 1. Для разграничения, при возвращении нуля, проверьте, равен ли первый байт s нулю. Если да, то входные данные были NUL; если нет, входные данные содержали ошибку. Или вы можете использовать "utf8n_to_uvchr_error".

Некоторые кодовые точки считаются проблемными. Это суррогаты Unicode, не-символы Unicode и кодовые точки, превышающие максимальное значение Unicode 0x10FFFF. По умолчанию они считаются обычными кодовыми точками, но в некоторых ситуациях требуется специальная обработка, которая может быть задана с помощью параметра flags. Если flags содержит UTF8_DISALLOW_ILLEGAL_INTERCHANGE, все три класса обрабатываются как ошибки и обрабатываются как таковые. Флаги UTF8_DISALLOW_SURROGATE, UTF8_DISALLOW_NONCHAR, и UTF8_DISALLOW_SUPER (означающий превышение максимального значения Unicode) могут быть установлены для запрета этих категорий индивидуально. UTF8_DISALLOW_ILLEGAL_INTERCHANGE ограничивает допустимые входные данные строго определёнными традиционно UTF-8, определёнными Unicode. Используйте UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE для использования определения строгости, заданного в Unicode Corrigendum #9. Разница между традиционной строгостью и строгостью C9 заключается в том, что последняя не запрещает не-символьные кодовые точки. (Однако они всё ещё не рекомендуются.) Более подробную информацию см. в "Не-символьные кодовые точки" в perlunicode.

Флаги UTF8_WARN_ILLEGAL_INTERCHANGE, UTF8_WARN_ILLEGAL_C9_INTERCHANGE, UTF8_WARN_SURROGATE, UTF8_WARN_NONCHAR, и UTF8_WARN_SUPER приведут к появлению сообщений об ошибках для соответствующих категорий, но в противном случае кодовые точки считаются допустимыми (не ошибочными). Чтобы сделать категорию одновременно ошибочной и генерирующей предупреждения, укажите флаги WARN и DISALLOW. (Однако обратите внимание, что предупреждения не генерируются, если они отключены лексически или если также указан UTF8_CHECK_ONLY.)

Очень высокие кодовые точки никогда не были указаны ни в одном стандарте и требуют расширения UTF-8 для выражения, которое Perl делает. Вероятно, программы, написанные не на Perl, не смогут читать файлы, содержащие эти кодовые точки; также Perl не поймёт файлы, написанные с помощью другого расширения. По этим причинам существует отдельный набор флагов, которые могут предупреждать и/или запрещать эти очень высокие кодовые точки, даже если другие кодовые точки, превышающие Unicode, принимаются. Это флаги UTF8_WARN_PERL_EXTENDED и UTF8_DISALLOW_PERL_EXTENDED. Более подробную информацию см. в "UTF8_GOT_PERL_EXTENDED". Конечно, UTF8_DISALLOW_SUPER обработает все кодовые точки, превышающие Unicode, включая эти, как ошибки. (Обратите внимание, что стандарт Unicode считает всё, что превышает 0x10FFFF, недопустимым, но существуют стандарты, предшествующие ему, которые допускают до 0x7FFF_FFFF (2**31 -1))

Несколько вводящее в заблуждение синоним для UTF8_WARN_PERL_EXTENDED сохраняется для обратной совместимости: UTF8_WARN_ABOVE_31_BIT. Аналогично, UTF8_DISALLOW_ABOVE_31_BIT может быть использован вместо более точного UTF8_DISALLOW_PERL_EXTENDED. Названия вводят в заблуждение, потому что эти флаги могут применяться к кодовым точкам, которые на самом деле помещаются в 31 бит. Это происходит на платформах EBCDIC и иногда, когда присутствует ошибка длинной последовательности. Новые имена точно описывают ситуацию во всех случаях.

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

UV  utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen,
                   const U32 flags)
utf8n_to_uvchr_error

ЭТУ ФУНКЦИЮ СЛЕДУЕТ ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛИЗИРОВАННЫХ СЛУЧАЯХ. Большинство кодов должно использовать "utf8_to_uvchr_buf"() вместо прямого вызова этой функции.

Эта функция предназначена для кодов, которым необходимо знать точные нарушения при обнаружении ошибки. Если вам также необходимо знать сгенерированные предупреждающие сообщения, используйте "utf8n_to_uvchr_msgs"() вместо этого.

Она похожа на "utf8n_to_uvchr" , но принимает дополнительный параметр, помещённый после всех остальных, errors. Если этот параметр равен 0, эта функция ведет себя идентично "utf8n_to_uvchr". В противном случае, errors должен указывать на переменную U32, которую эта функция устанавливает для обозначения найденных ошибок. По возвращении, если *errors равно 0, ошибок не найдено. В противном случае, *errors является побитовым OR битов, описанных в списке ниже. Некоторые из этих битов будут установлены, если нарушение найдено, даже если входной параметр flags указывает, что данное нарушение разрешено; эти исключения отмечены:

UTF8_GOT_PERL_EXTENDED

Последовательность ввода не является стандартным UTF-8, а является расширением Perl. Этот бит устанавливается только если входной параметр flags содержит либо флаг UTF8_DISALLOW_PERL_EXTENDED, либо флаг UTF8_WARN_PERL_EXTENDED.

Код символов выше 0x7FFF_FFFF (2**31 - 1) никогда не был указан ни в одном стандарте, и поэтому для их выражения необходимо использовать какое-то расширение. Perl использует естественное расширение UTF-8 для представления значений до 2**36-1, и придумал дополнительное расширение для представления еще более высоких значений, так что любой символ, помещающийся в 64-битовое слово, может быть представлен. Текст, использующий эти расширения, вероятно, не будет переносимым в код, не связанный с Perl. Мы объединили оба этих расширения и называем их расширенным UTF-8 Perl. Существуют и другие расширения, которые люди придумали, несовместимые с Perl.

На платформах EBCDIC, начиная с Perl v5.24, расширение Perl для представления чрезвычайно больших символов включается при значении 0x3FFF_FFFF (2**30 - 1), которое меньше, чем в ASCII. До этого код символов 2**31 и выше просто не представлялись, и использовался другой, несовместимый метод для представления кодов символов между 2**30 и 2**31 - 1.

На обеих платформах, ASCII и EBCDIC, UTF8_GOT_PERL_EXTENDED устанавливается, если используется расширенный UTF-8 Perl.

В более ранних версиях Perl этот бит назывался UTF8_GOT_ABOVE_31_BIT, который вы можете использовать для обратной совместимости. Это название вводит в заблуждение, так как этот флаг может быть установлен, когда символ фактически помещается в 31 бит. Это происходит на платформах EBCDIC и иногда, когда также присутствует нарушение недостаточного заполнения. Новое имя точно описывает ситуацию во всех случаях.

UTF8_GOT_CONTINUATION

Последовательность входных данных была неправильной, так как первый байт был байтом продолжения UTF-8.

UTF8_GOT_EMPTY

Входной параметр curlen был равен 0.

UTF8_GOT_LONG

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

До версии Unicode 3.1 программы могли принимать это нарушение, но было обнаружено, что это создаёт проблемы безопасности.

UTF8_GOT_NONCHAR

Код символа, представленный последовательностью UTF-8 входных данных, представляет собой не-символ Unicode. Этот бит устанавливается только если входной параметр flags содержит либо флаг UTF8_DISALLOW_NONCHAR, либо флаг UTF8_WARN_NONCHAR.

UTF8_GOT_NON_CONTINUATION

Последовательность входных данных была неправильной, так как в позиции, где должен быть только байт продолжения, был обнаружен байт не-продолжения. См. также "UTF8_GOT_SHORT".

UTF8_GOT_OVERFLOW

Последовательность входных данных была неправильной, так как она соответствует символу, который не может быть представлен в количестве битов, доступных в регистре IV на текущей платформе.

UTF8_GOT_SHORT

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

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

  • Параметр длины curlen , переданный в функцию, был слишком мал, и функция не смогла рассмотреть все необходимые байты.

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

  • Это реальная ошибка, и частичная последовательность - всё, что мы получим.

UTF8_GOT_SUPER

Последовательность входных данных была неправильной, так как она соответствует символу вне Unicode; то есть, символу, превышающему максимальное допустимое значение Unicode. Этот бит устанавливается только если входной параметр flags содержит либо флаг flags, либо флаг UTF8_DISALLOW_SUPER.

UTF8_GOT_SURROGATE

Последовательность входных данных была неправильной, так как она соответствует зарезервированному коду символа UTF-16. Этот бит устанавливается только если входной параметр flags содержит либо флаг UTF8_DISALLOW_SURROGATE, либо флаг UTF8_WARN_SURROGATE.

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

UV  utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
                         STRLEN *retlen, const U32 flags,
                         U32 *errors)
utf8n_to_uvchr_msgs

ЭТУ ФУНКЦИЮ СЛЕДУЕТ ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛИЗИРОВАННЫХ СЛУЧАЯХ. Большинство кодов должны использовать "utf8_to_uvchr_buf"() вместо прямого вызова этой функции.

Эта функция предназначена для кодов, которым необходимо знать точные нарушения при обнаружении ошибки и получать соответствующие предупреждающие и/или сообщения об ошибках, возвращаемые вызывающему коду, а не отображаемые. Все сообщения, которые были бы отображены, если бы были включены все лексические предупреждения, будут возвращены.

Она похожа на "utf8n_to_uvchr_error" , но принимает дополнительный параметр, помещённый после всех остальных, msgs. Если этот параметр равен 0, эта функция ведет себя идентично "utf8n_to_uvchr_error". В противном случае, msgs должен указывать на переменную AV *, в которой эта функция создаёт новый массив ассоциативных элементов для хранения любых соответствующих сообщений. Элементы массива упорядочены так, что первое сообщение, которое должно было быть отображено, находится в 0-м элементе и так далее. Каждый элемент - это хеш с тремя парами «ключ-значение»:

text

Текст сообщения как SVpv.

warn_categories

Категория (или категории) предупреждения, упакованная в SVuv.

flag

Один флаг, связанный с этим сообщением, в SVuv. Бит соответствует некоторому биту в возвращаемом значении *errors, таком как UTF8_GOT_LONG.

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

Если передаётся флаг UTF8_CHECK_ONLY, никакие предупреждения не генерируются, и, следовательно, AV не создаётся.

Вызывающая функция, конечно, несет ответственность за освобождение любого возвращённого AV.

UV  utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
                        STRLEN *retlen, const U32 flags,
                        U32 *errors, AV **msgs)
UTF8_SAFE_SKIP

Возвращает 0, если s >= e; в противном случае возвращает число байтов в кодированном UTF-8 символе, первый байт которого указан в s. Но никогда не возвращает значение свыше e. В сборках с отладкой утверждается, что s <= e.

STRLEN  UTF8_SAFE_SKIP(char* s, char* e)
UTF8SKIP

Возвращает число байтов неискаженного кодированного UTF-8 символа, первый (возможно, единственный) байт которого указан в s.

Если существует возможность искажённого ввода, используйте вместо этого:

"UTF8_SAFE_SKIP" если вы знаете максимальный указатель конца буфера, на который указывает s; или
"UTF8_CHK_SKIP" если вы этого не знаете.

Лучше перестроить ваш код так, чтобы указатель конца был передан, чтобы вы знали, что это на самом деле является на момент этого вызова, но если это невозможно, "UTF8_CHK_SKIP" может минимизировать вероятность обращения за пределы буфера ввода.

STRLEN  UTF8SKIP(char* s)
UTF8_SKIP

Это синоним для "UTF8SKIP"

STRLEN  UTF8_SKIP(char* s)
utf8_to_bytes

ПРИМЕЧАНИЕ: utf8_to_bytes является экспериментальным и может быть изменён или удалён без предварительного уведомления.

Преобразует строку "s" длиной *lenp из UTF-8 в кодировку байтов по умолчанию. В отличие от "bytes_to_utf8", это перезаписывает исходную строку и обновляет *lenp для отображения новой длины. Возвращает ноль при ошибке (оставляя "s" неизменным), устанавливая *lenp в -1.

По успешном возврате число вариаций в строке можно вычислить, сохранив значение *lenp до вызова и вычитав значение *lenp после вызова.

Если вам нужна копия строки, см. "bytes_from_utf8".

U8 *  utf8_to_bytes(U8 *s, STRLEN *lenp)
utf8_to_uvchr

DEPRECATED! Планируется удалить utf8_to_uvchr из будущей версии Perl. Не используйте его в новом коде; удалите его из существующего кода.

Возвращает внутренний код символа первого символа в строке s, которая предполагается в кодировке UTF-8; retlen будет установлено в длину этого символа в байтах.

Некоторые, но не все, ошибки UTF-8 обнаруживаются, и, фактически, некоторые ошибочные входные данные могут привести к чтению за пределами буфера ввода, поэтому эта функция устарела. Используйте "utf8_to_uvchr_buf" вместо неё.

Если s указывает на одну из обнаруженных ошибок, и включены предупреждения UTF8, возвращается ноль, а *retlen устанавливается (если retlen не NULL) в -1. Если эти предупреждения выключены, вычисленное значение, если оно определено (или ЗАМЕЩАЮЩИЙ СИМВОЛ Юникода, если нет), будет возвращено без изменений, и *retlen будет установлено (если retlen не NULL), так что (s + *retlen) будет следующей возможной позицией в s, которая могла бы начать правильный символ. Смотрите "utf8n_to_uvchr" для получения подробностей о том, когда возвращается ЗАМЕЩАЮЩИЙ СИМВОЛ.

UV  utf8_to_uvchr(const U8 *s, STRLEN *retlen)
utf8_to_uvchr_buf

Возвращает внутренний код символа первого символа в строке s, которая предполагается в кодировке UTF-8; send указывает на позицию, следующую за концом s. *retlen будет установлено в длину этого символа в байтах.

Если s не указывает на правильно сформированный символ UTF-8, и включены предупреждения UTF8, возвращается ноль, а *retlen устанавливается (если retlen не NULL) в -1. Если эти предупреждения выключены, вычисленное значение, если оно определено (или ЗАМЕЩАЮЩИЙ СИМВОЛ Юникода, если нет), будет возвращено без изменений, и *retlen будет установлено (если retlen не NULL) так, что (s + *retlen) будет следующей возможной позицией в s, которая могла бы начать правильный символ. Смотрите "utf8n_to_uvchr" для получения подробностей о том, когда возвращается ЗАМЕЩАЮЩИЙ СИМВОЛ.

UV  utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen)
UVCHR_IS_INVARIANT

Принимает значение 1, если представление кодового символа cp одинаково, независимо от того, закодирован ли он в UTF-8; в противном случае принимает значение 0. Неизменные символы UTF-8 могут копироваться без изменений при преобразовании в/из UTF-8, что экономит время. cp — это символ Юникода, если он больше 255; в противном случае — это символ платформы.

bool  UVCHR_IS_INVARIANT(UV cp)
UVCHR_SKIP

Возвращает количество байтов, необходимых для представления кодового символа cp при кодировании в UTF-8. cp — это внутренний (ASCII или EBCDIC) кодовый символ, если он меньше 255; в противном случае — кодовый символ Юникода.

STRLEN  UVCHR_SKIP(UV cp)
uvchr_to_utf8_flags

Добавляет представление символа UTF-8 внутреннего кодового символа uv в конец строки d; d должно иметь как минимум UVCHR_SKIP(uv)+1 (до UTF8_MAXBYTES+1) свободных байтов. Возвращаемое значение — указатель на байт после конца нового символа. Другими словами,

d = uvchr_to_utf8_flags(d, uv, flags);

или, в большинстве случаев,

d = uvchr_to_utf8_flags(d, uv, 0);

Это осознанный способ сказать

*(d++) = uv;

Если flags равно 0, эта функция принимает в качестве входных данных любой кодовый символ от 0 до IV_MAX. IV_MAX обычно равно 0x7FFF_FFFF в 32-разрядном слове.

Указание flags может дополнительно ограничить разрешённые значения и не вызывать предупреждения следующим образом:

Если uv — это суррогатный кодовый символ Юникода, и UNICODE_WARN_SURROGATE установлено, функция выдаст предупреждение, при условии, что включены предупреждения UTF8. Если вместо этого установлено UNICODE_DISALLOW_SURROGATE, функция завершится ошибкой и вернёт NULL. Если оба флага установлены, функция выдаст предупреждение и вернёт NULL.

Аналогично, флаги UNICODE_WARN_NONCHAR и UNICODE_DISALLOW_NONCHAR влияют на то, как функция обрабатывает несимвол Юникода.

И аналогичным образом, флаги UNICODE_WARN_SUPER и UNICODE_DISALLOW_SUPER влияют на обработку кодовых символов, превышающих максимальное значение Юникода 0x10FFFF. Языки, отличные от Perl, могут не поддерживать файлы, содержащие такие символы.

Флаг UNICODE_WARN_ILLEGAL_INTERCHANGE выбирает все три вышеупомянутых флага WARN; а UNICODE_DISALLOW_ILLEGAL_INTERCHANGE выбирает все три флага DISALLOW. UNICODE_DISALLOW_ILLEGAL_INTERCHANGE ограничивает допустимые входные данные строгим UTF-8, традиционно определяемым Юникодом. Аналогично, UNICODE_WARN_ILLEGAL_C9_INTERCHANGE и UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE являются сокращениями для выбора флагов выше Юникода и суррогатных символов, но не несимволов, как определено в Поправке к стандарту Юникода #9. См. "Несимвольные кодовые точки" в perlunicode.

Чрезвычайно высокие кодовые точки никогда не были определены в каком-либо стандарте и требуют расширения UTF-8 для представления, что Perl делает. Вероятно, программы, написанные на чём-то, кроме Perl, не смогут читать файлы, содержащие такие символы; так же Perl не сможет прочитать файлы, созданные с использованием другого расширения. По этим причинам существует отдельный набор флагов, которые могут предупреждать и/или запрещать эти чрезвычайно высокие кодовые точки, даже если другие символы, превышающие Юникод, принимаются. Это флаги UNICODE_WARN_PERL_EXTENDED и UNICODE_DISALLOW_PERL_EXTENDED. Для получения дополнительной информации см. "UTF8_GOT_PERL_EXTENDED". Конечно, UNICODE_DISALLOW_SUPER будет рассматривать все кодовые точки, превышающие Юникод, включая эти, как ошибки.

(Обратите внимание, что стандарт Юникода рассматривает всё, что превышает 0x10FFFF, как некорректное, но существуют стандарты, предшествующие ему, которые разрешают до 0x7FFF_FFFF (2**31 -1)).

Несколько вводящее в заблуждение синоним для UNICODE_WARN_PERL_EXTENDED сохраняется для обратной совместимости: UNICODE_WARN_ABOVE_31_BIT. Аналогично, UNICODE_DISALLOW_ABOVE_31_BIT можно использовать вместо более точного названия UNICODE_DISALLOW_PERL_EXTENDED. Названия вводят в заблуждение, потому что на платформах EBCDIC эти флаги могут применяться к кодовым символам, которые фактически умещаются в 31 бит. Новые имена точно описывают ситуацию во всех случаях.

U8 *  uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
uvchr_to_utf8_flags_msgs

ЭТУ ФУНКЦИЮ НЕОБХОДИМО ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛИЗИРОВАННЫХ СЛУЧАЯХ.

Большинству кодов следует использовать "uvchr_to_utf8_flags"() вместо непосредственного вызова этой функции.

Эта функция предназначена для кода, который хочет, чтобы все предупреждения и/или сообщения об ошибках возвращались вызывающей функции, а не отображались. Все сообщения, которые были бы отображены, если бы были включены все лексические предупреждения, будут возвращены.

Это как "uvchr_to_utf8_flags", но с дополнительным параметром после всех остальных, msgs. Если этот параметр равен 0, функция ведет себя идентично "uvchr_to_utf8_flags". В противном случае, msgs должен быть указателем на переменную типа HV *, в которой эта функция создаёт новый HV для хранения любых необходимых сообщений. В хэш сохраняется три пары ключ-значение следующим образом:

text

Текст сообщения в виде SVpv.

warn_categories

Категория (или категории) предупреждений, упакованные в SVuv.

flag

Единый флаг, связанный с этим сообщением, в SVuv. Этот бит соответствует некоторому биту в значении возвращаемого *errors типа, например, UNICODE_GOT_SURROGATE.

Важно отметить, что при указании этого параметра как не-NULL, все предупреждения, которые эта функция в противном случае сгенерировала, будут подавлены, а вместо этого будут помещены в *msgs. Вызывающая функция может проверить состояние лексических предупреждений (или нет), чтобы решить, что делать с возвращенными сообщениями.

Вызывающая функция, конечно, отвечает за освобождение возвращённого HV.

U8 *  uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags, HV **msgs)
uvchr_to_utf8

Добавляет представление символа UTF-8 внутреннего кодового символа uv в конец строки d; d должна иметь как минимум UVCHR_SKIP(uv)+1 (до UTF8_MAXBYTES+1) свободных байтов. Возвращаемое значение — указатель на байт после конца нового символа. Другими словами,

d = uvchr_to_utf8(d, uv);

является рекомендуемым способом осознанного указания кодового символа широкого внутреннего типа

*(d++) = uv;

Эта функция принимает в качестве входных данных любой кодовый символ от 0 до IV_MAX. IV_MAX обычно равно 0x7FFF_FFFF в 32-битном слове.

Можно запретить или предупредить о кодовых символах, не входящих в Юникод, или о проблематичных, используя "uvchr_to_utf8_flags".

U8 *  uvchr_to_utf8(U8 *d, UV uv)

Функции-утилиты

C_ARRAY_END

Возвращает указатель на элемент, следующий за последним элементом входного массива C.

void *  C_ARRAY_END(void *a)
C_ARRAY_LENGTH

Возвращает количество элементов в входном массиве C (т. е. индексы от нуля должны быть меньше, но не равны).

STRLEN  C_ARRAY_LENGTH(void *a)
getcwd_sv

Заполняет sv текущим рабочим каталогом

int  getcwd_sv(SV *sv)
IN_PERL_COMPILETIME

Возвращает 1, если этот макрос вызывается во время фазы компиляции программы; в противном случае 0.

bool  IN_PERL_COMPILETIME
IN_PERL_RUNTIME

Возвращает 1, если этот макрос вызывается во время фазы выполнения программы; в противном случае 0.

bool  IN_PERL_RUNTIME
IS_SAFE_SYSCALL

То же самое, что и "is_safe_syscall".

bool  IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
                      NN const char *what, NN const char *op_name)
is_safe_syscall

Проверяет, что данный pv (с длиной len) не содержит внутренних NUL символов. Если содержит, устанавливает errno в ENOENT, при необходимости выводит предупреждение с использованием категории syscalls, и возвращает FALSE.

Возвращает TRUE, если имя безопасно.

what и op_name используются в любом предупреждении.

Используется макросом IS_SAFE_SYSCALL(). 

bool  is_safe_syscall(const char *pv, STRLEN len,
                      const char *what, const char *op_name)
my_setenv

Обёртка для функции setenv(3) C-библиотеки. Не используйте последнюю, так как у версии Perl есть необходимые меры безопасности

void  my_setenv(const char *nam, const char *val)
newPADxVOP

Создаёт, проверяет и возвращает op, содержащий смещение блока. type — это код операции, который должен быть одним из OP_PADSV, OP_PADAV, OP_PADHV или OP_PADCV. Возвращаемый op будет иметь поле op_targ установленное аргументом padix.

Это удобно при построении большого дерева op в вложенных функциях, так как это позволяет избежать необходимости непосредственного хранения op блока для установки поля op_targ в качестве побочного эффекта. Например:

o = op_append_elem(OP_LINESEQ, o,
    newPADxVOP(OP_PADSV, 0, padix));
OP *  newPADxVOP(I32 type, I32 flags, PADOFFSET padix)
phase_name

Возвращает имя заданной фазы в виде строки с нулевым завершением.

Например, чтобы напечатать трассировку стека, включающую текущую фазу интерпретатора, можно сделать так:

const char* phase_name = phase_name(PL_phase);
mess("This is weird. (Perl phase: %s)", phase_name);
const char * const  phase_name(enum perl_phase)
Poison

PoisonWith(0xEF) для перехвата доступа к освобождённой памяти.

void  Poison(void* dest, int nitems, type)
PoisonFree

PoisonWith(0xEF) для перехвата доступа к освобождённой памяти.

void  PoisonFree(void* dest, int nitems, type)
PoisonNew

PoisonWith(0xAB) для перехвата доступа к выделенной, но не инициализированной памяти.

void  PoisonNew(void* dest, int nitems, type)
PoisonWith

Заполнение памяти байтовым шаблоном (повторяющимся байтом), который, надеемся, перехватывает попытки доступа к неинициализированной памяти.

void  PoisonWith(void* dest, int nitems, type, U8 byte)
StructCopy

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

void  StructCopy(type *src, type *dest, type)
sv_destroyable

Простая процедура, сообщающая, что объект может быть уничтожен, когда отсутствует модуль совместного использования. Она игнорирует свой единственный аргумент SV и возвращает «true». Существует, чтобы избежать проверки указателя на функцию NULL и потому, что она потенциально может выдавать предупреждение при определённом уровне строгости.

bool  sv_destroyable(SV *sv)
sv_nosharing

Простая процедура, которая «обменивает» SV, когда отсутствует модуль совместного использования. Или «блокирует» его. Или «разблокирует» его. Другими словами, игнорирует свой единственный аргумент SV. Существует, чтобы избежать проверки указателя на функцию NULL и потому, что она потенциально может выдавать предупреждение при определённом уровне строгости.

void  sv_nosharing(SV *sv)

Версионирование

new_version

Возвращает новый объект версии, основанный на переданном SV:

SV *sv = new_version(SV *ver);

Не изменяет переданный SV. Обратитесь к "upg_version", если хотите обновить SV.

SV *  new_version(SV *ver)
PERL_REVISION

DEPRECATED! Планируется удалить PERL_REVISION из будущих выпусков Perl. Не используйте его для нового кода; удалите из существующего кода.

Главное число компонента интерпретатора Perl, который в настоящее время компилируется или выполняется. С 1993 по 2020 год оно изменялось.

Вместо этого используйте одну из макрокоманд сравнения версий. См. "PERL_VERSION_EQ".

PERL_SUBVERSION

DEPRECATED! Планируется удалить PERL_SUBVERSION из будущих выпусков Perl. Не используйте его для нового кода; удалите из существующего кода.

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

Вместо этого используйте одну из макрокоманд сравнения версий. См. "PERL_VERSION_EQ".

PERL_VERSION

DEPRECATED! Планируется удалить PERL_VERSION из будущих выпусков Perl. Не используйте его для нового кода; удалите из существующего кода.

Младшее число компонента версии интерпретатора Perl, который в настоящее время компилируется или выполняется. С 1993 по 2020 год оно изменялось от 0 до 33.

Вместо этого используйте одну из макрокоманд сравнения версий. См. "PERL_VERSION_EQ".

PERL_VERSION_EQ
PERL_VERSION_GE
PERL_VERSION_GT
PERL_VERSION_LE
PERL_VERSION_LT
PERL_VERSION_NE

Возвращает true или false в зависимости от того, соответствует ли текущая компилируемая версия Perl указанным отношениям к версии Perl, заданной параметрами. Например,

#if PERL_VERSION_GT(5,24,2)
  code that will only be compiled on perls after v5.24.2
#else
  fallback code
#endif

Обратите внимание, что это можно использовать для принятия решений во время компиляции.

Вы можете использовать специальное значение '*' для последнего числа, чтобы означать все возможные значения для него. Таким образом,

#if PERL_VERSION_EQ(5,31,'*')

означает все версии Perl серии 5.31. И

#if PERL_VERSION_NE(5,24,'*')

означает все версии Perl, КРОМЕ 5.24. И

#if PERL_VERSION_LE(5,9,'*')

эффективно эквивалентно

#if PERL_VERSION_LT(5,10,0)

Это означает, что при переходе от устаревшей, теперь не рекомендуемой, макрокоманды PERL_VERSION к использованию этой макрокоманды вам не нужно так много думать:

#if PERL_VERSION <= 9

становится

#if PERL_VERSION_LE(5,9,'*')
bool  PERL_VERSION_EQ(const U8 major, const U8 minor,
                      const U8 patch)
prescan_version

Проверяет, может ли заданная строка быть обработана как объект версии, но фактически не выполняет обработку. Может использовать строгие или нестрогие правила проверки. Может по желанию установить ряд переменных подсказок для экономии времени кода обработки при разборе.

const char *  prescan_version(const char *s, bool strict,
                              const char **errstr, bool *sqv,
                              int *ssaw_decimal, int *swidth,
                              bool *salpha)
scan_version

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

Функция должна вызываться с уже существующим SV, как показано ниже:

sv = newSV(0);
s = scan_version(s, SV *sv, bool qv);

Выполняет предварительную обработку строки, чтобы убедиться, что она имеет правильные характеристики версии. Помечает объект, если он содержит символ подчёркивания (который обозначает альфа-версию). Булевое значение qv указывает, что версия должна интерпретироваться как имеющая несколько десятичных знаков, даже если их нет.

const char *  scan_version(const char *s, SV *rv, bool qv)
upg_version

Непосредственное обновление переданного SV до объекта версии.

SV *sv = upg_version(SV *sv, bool qv);

Возвращает указатель на обновлённый SV. Установите булево значение qv, если вы хотите заставить интерпретацию этого SV как «расширенной» версии.

SV *  upg_version(SV *ver, bool qv)
vcmp

Сравнение, учитывающее объекты версии. Оба операнда должны быть преобразованы в объекты версии.

int  vcmp(SV *lhv, SV *rhv)
vnormal

Принимает объект версии и возвращает нормализованное строковое представление. Вызов подобен:

sv = vnormal(rv);

ПРИМЕЧАНИЕ: вы можете передать либо сам объект, либо SV, содержащийся в RV.

Возвращаемый SV имеет счётчик ссылок 1.

SV *  vnormal(SV *vs)
vnumify

Принимает объект версии и возвращает нормализованное представление с плавающей точкой. Вызов подобен:

sv = vnumify(rv);

ПРИМЕЧАНИЕ: вы можете передать либо сам объект, либо SV, содержащийся в RV.

Возвращаемый SV имеет счётчик ссылок 1.

SV *  vnumify(SV *vs)
vstringify

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

Возвращаемый SV имеет счётчик ссылок 1.

SV *  vstringify(SV *vs)
vverify

Проверяет, содержит ли SV допустимую внутреннюю структуру для объекта версии. Ему можно передать либо сам объект версии (RV), либо сам хеш (HV). Если структура допустима, возвращается HV. Если структура недопустима, возвращается NULL.

SV *hv = vverify(sv);

Обратите внимание, что он проверяет только минимальную структуру (чтобы не путаться с производными классами, которые могут содержать дополнительные записи в хеше):

  • SV является HV или ссылкой на HV

  • Хеш содержит ключ "version"

  • Ключ "version" содержит ссылку на AV в качестве значения

SV *  vverify(SV *vs)

Предупреждения и аварийный выход

Во всех этих вызовах параметры U32 wn — это константы категорий предупреждений. Вы можете найти доступные в настоящее время в "Иерархия категорий" в предупреждениях, просто заглавными буквами запишите названия и префикс их WARN_. Например, категория void в программе Perl становится WARN_VOID в коде XS и передаётся одному из вызовов ниже.

ckWARN
ckWARN2
ckWARN3
ckWARN4

Эти функции возвращают булево значение, указывающее, включены ли предупреждения для любой из категорий предупреждений в параметрах: w, w1, ....

Если какие-либо категории по умолчанию включены, даже если не в области действия use warnings, используйте макрокоманды "ckWARN_d".

Категории должны быть полностью независимыми, одна не может быть подклассом другой.

bool  ckWARN (U32 w)
bool  ckWARN2(U32 w1, U32 w2)
bool  ckWARN3(U32 w1, U32 w2, U32 w3)
bool  ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
ckWARN_d
ckWARN2_d
ckWARN3_d
ckWARN4_d

Как "ckWARN", но для использования только тогда, когда категория предупреждения включена по умолчанию, даже если не в области действия use warnings.

bool  ckWARN_d (U32 w)
bool  ckWARN2_d(U32 w1, U32 w2)
bool  ckWARN3_d(U32 w1, U32 w2, U32 w3)
bool  ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
ck_warner
ck_warner_d

Если ни одна из категорий предупреждений, заданных err, не включена, ничего не делать; в противном случае вызвать "warner" или "warner_nocontext" с переданными параметрами.

err должна быть одной из макрокоманд "packWARN", packWARN2, packWARN3, packWARN4 с соответствующим количеством категорий предупреждений.

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

ПРИМЕЧАНИЕ: ck_warner должен быть явно вызван как Perl_ck_warner с параметром aTHX_.

ПРИМЕЧАНИЕ: ck_warner_d должен быть явно вызван как Perl_ck_warner_d с параметром aTHX_. 

void  Perl_ck_warner(pTHX_ U32 err, const char *pat, ...)
CLEAR_ERRSV

Очистить содержимое $@, установив его в пустую строку.

Это заменяет любой только для чтения SV свежим SV и удаляет всю магию.

void  CLEAR_ERRSV()
croak
croak_nocontext

Это интерфейсы XS для функции Perl's die.

Они принимают шаблон форматирования в стиле sprintf и список аргументов, которые используются для генерации сообщения об ошибке. Если сообщение не заканчивается новой строкой, то оно будет дополнено указанием текущего местоположения в коде, как описано для "mess_sv".

Сообщение об ошибке будет использовано как исключение, по умолчанию возвращая управление ближайшему содержащему eval, но подлежит модификации обработчиком $SIG{__DIE__}. В любом случае, эти функции croak никогда не возвращают значение нормально.

По историческим причинам, если pat равно null, то содержимое ERRSV ($@) будет использовано в качестве сообщения об ошибке или объекта вместо построения сообщения об ошибке из аргументов. Если вы хотите бросить объект, не являющийся строкой, или построить сообщение об ошибке в SV самостоятельно, предпочтительнее использовать функцию "croak_sv", которая не включает в себя перезапись ERRSV.

Эти два варианта отличаются только тем, что croak_nocontext не принимает параметр контекста потока (aTHX). Обычно предпочтительнее, так как он занимает меньше байтов кода, чем обычный Perl_croak, а время редко является критическим ресурсом, когда вы собираетесь бросить исключение.

ПРИМЕЧАНИЕ: croak должен быть явно вызван как Perl_croak с параметром aTHX_. 

void  Perl_croak     (pTHX_ const char *pat, ...)
void  croak_nocontext(const char *pat, ...)
croak_no_modify

Это обобщает распространённую причину завершения работы, генерируя более компактный объектный код, чем использование универсальной функции Perl_croak. Это точно эквивалентно Perl_croak(aTHX_ "%s", PL_no_modify) (что расширяется до чего-то вроде «Попытка изменения значения только для чтения»).

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

void  croak_no_modify()
croak_sv

Это интерфейс XS для функции Perl's die.

baseex — это сообщение об ошибке или объект. Если это ссылка, она будет использована как есть. В противном случае она используется как строка, и если она не заканчивается новой строкой, она будет дополнена указанием текущего местоположения в коде, как описано для "mess_sv".

Сообщение об ошибке или объект будут использованы как исключение, по умолчанию возвращая управление ближайшему содержащему eval, но подлежит модификации обработчиком $SIG{__DIE__}. В любом случае, функция croak_sv никогда не возвращает значение нормально.

Для завершения работы с простым строковым сообщением может быть удобнее использовать функцию "croak".

void  croak_sv(SV *baseex)
die
die_nocontext

Они ведут себя так же, как "croak", за исключением типа возвращаемого значения. Их следует использовать только там, где требуется тип возвращаемого значения OP *. Они фактически никогда не возвращают значение.

Эти два варианта отличаются только тем, что die_nocontext не принимает параметр контекста потока (aTHX), поэтому используется в ситуациях, когда у вызывающего объекта ещё нет контекста потока.

ПРИМЕЧАНИЕ: die должен быть явно вызван как Perl_die с параметром aTHX_. 

OP *  Perl_die     (pTHX_ const char *pat, ...)
OP *  die_nocontext(const char *pat, ...)
die_sv

Она ведет себя так же, как "croak_sv", за исключением типа возвращаемого значения. Его следует использовать только там, где требуется тип возвращаемого значения OP *. Функция фактически никогда не возвращает значение.

OP *  die_sv(SV *baseex)
ERRSV

Возвращает SV для $@, создавая его при необходимости.

SV *  ERRSV
packWARN
packWARN2
packWARN3
packWARN4

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

U32  packWARN (U32 w1)
U32  packWARN2(U32 w1, U32 w2)
U32  packWARN3(U32 w1, U32 w2, U32 w3)
U32  packWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
SANE_ERRSV

Очистка ERRSV, чтобы мы могли безопасно установить его.

Заменяет любое неизменяемое SV новой копией с возможностью записи и удаляет всю магию.

void  SANE_ERRSV()
vcroak

Это интерфейс XS для функции Perl's die.

pat и args — это шаблон форматирования в стиле sprintf и заключённый список аргументов. Они используются для генерации строкового сообщения. Если сообщение не заканчивается новой строкой, оно будет дополнено указанием текущего местоположения в коде, как описано для "mess_sv".

Сообщение об ошибке будет использовано как исключение, по умолчанию возвращая управление ближайшему содержащему eval, но подлежит модификации обработчиком $SIG{__DIE__}. В любом случае, функция croak никогда не возвращает значение нормально.

По историческим причинам, если pat равно null, то содержимое ERRSV ($@) будет использовано в качестве сообщения об ошибке или объекта вместо построения сообщения об ошибке из аргументов. Если вы хотите бросить объект, не являющийся строкой, или построить сообщение об ошибке в SV самостоятельно, предпочтительнее использовать функцию "croak_sv", которая не включает в себя перезапись ERRSV. 

void  vcroak(const char *pat, va_list *args)
vwarn

Это интерфейс XS для функции Perl's warn.

Это похоже на "warn", но args — это заключённый список аргументов.

В отличие от "vcroak", pat не может быть null.

void  vwarn(const char *pat, va_list *args)
vwarner

Это похоже на "warner", но args — это заключённый список аргументов.

void  vwarner(U32 err, const char *pat, va_list *args)
warn
warn_nocontext

Это интерфейсы XS для функции Perl's warn.

Они принимают шаблон форматирования в стиле sprintf и список аргументов, которые используются для генерации строкового сообщения. Если сообщение не заканчивается новой строкой, то оно будет дополнено указанием текущего местоположения в коде, как описано для "mess_sv".

Сообщение об ошибке или объект по умолчанию будут выведены в стандартный вывод ошибки, но это подлежит модификации обработчиком $SIG{__WARN__}.

В отличие от "croak", pat не может быть null.

Эти два варианта отличаются только тем, что warn_nocontext не принимает параметр контекста потока (aTHX), поэтому используется в ситуациях, когда у вызывающего объекта ещё нет контекста потока.

ПРИМЕЧАНИЕ: warn должен быть явно вызван как Perl_warn с параметром aTHX_. 

void  Perl_warn     (pTHX_ const char *pat, ...)
void  warn_nocontext(const char *pat, ...)
warner
warner_nocontext

Они выдают предупреждение указанной категории (или категорий), заданной err, используя шаблон форматирования в стиле sprintf pat и список аргументов.

err должен быть одним из макросов "packWARN", packWARN2, packWARN3, packWARN4, заполненных соответствующим количеством категорий предупреждений. Если какая-либо из категорий предупреждений, которые они определяют, является критической, возникает критическое исключение.

В любом случае, сообщение генерируется с помощью шаблона и аргументов. Если сообщение не заканчивается новой строкой, то оно будет дополнено указанием текущего местоположения в коде, как описано для "mess_sv".

Сообщение об ошибке или объект по умолчанию выводятся в стандартный вывод ошибки, но это подлежит модификации обработчиком $SIG{__WARN__}.

pat не может быть null.

Эти два варианта отличаются только тем, что warner_nocontext не принимает параметр контекста потока (aTHX), поэтому используется в ситуациях, когда у вызывающего объекта ещё нет контекста потока.

Эти функции отличаются от аналогично названных функций "warn", поскольку последние предназначены для XS-кода, чтобы безусловно отобразить предупреждение, тогда как эти предназначены для кода, который может компилировать программу Perl, и выполняет дополнительную проверку, чтобы увидеть, должно ли предупреждение быть критическим.

ПРИМЕЧАНИЕ: warner должен быть явно вызван как Perl_warner с параметром aTHX_. 

void  Perl_warner     (pTHX_ U32 err, const char *pat, ...)
void  warner_nocontext(U32 err, const char *pat, ...)
warn_sv

Это интерфейс XS для функции Perl's warn.

baseex — это сообщение об ошибке или объект. Если это ссылка, она будет использована как есть. В противном случае она используется как строка, и если она не заканчивается новой строкой, она будет дополнена указанием текущего местоположения в коде, как описано для "mess_sv".

Сообщение об ошибке или объект по умолчанию выводятся в стандартный вывод ошибки, но это подлежит модификации обработчиком $SIG{__WARN__}.

Для вывода простого строкового сообщения можно использовать функцию "warn".

void  warn_sv(SV *baseex)

XS

xsubpp компилирует XS-код в C. См. "xsubpp" в perlutil.

aMY_CXT

Описано в perlxs.

_aMY_CXT

Описано в perlxs.

aMY_CXT_

Описано в perlxs.

ax

Переменная, устанавливаемая xsubpp, чтобы указать смещение базового значения стека, используемая макросами ST, XSprePUSH и XSRETURN. Макрос dMARK должен быть вызван перед установкой переменной MARK. 

I32  ax
CLASS

Переменная, устанавливаемая xsubpp, чтобы указать имя класса для C++ XS-конструктора. Это всегда char*. См. "THIS". 

char*  CLASS
dAX

Устанавливает переменную ax. Обычно это обрабатывается автоматически xsubpp вызовом dXSARGS. 

dAX;
dAXMARK

Устанавливает переменную ax и переменную-маркер стека mark. Обычно это обрабатывается автоматически xsubpp вызовом dXSARGS. 

dAXMARK;
dITEMS

Настраивает переменную items. Обычно это выполняется автоматически xsubpp, вызывая dXSARGS. 

dITEMS;
dMY_CXT

Описание в perlxs.

dMY_CXT_SV

Сейчас заполнитель, который ничего не объявляет

dMY_CXT_SV;
dUNDERBAR

Настраивает любые переменные, необходимые макросу UNDERBAR. Раньше он определял padoff_du, но в настоящее время является пустой операцией. Однако настоятельно рекомендуется использовать его для обеспечения обратной совместимости в прошлом и будущем.

dUNDERBAR;
dXSARGS

Настраивает указатели стека и метки для XSUB, вызывая dSP и dMARK. Настраивает переменные ax и items, вызывая dAX и dITEMS. Обычно это выполняется автоматически xsubpp.

dXSARGS;
dXSI32

Настраивает переменную ix для XSUB, имеющего псевдонимы. Обычно это выполняется автоматически xsubpp.

dXSI32;
items

Переменная, настраиваемая xsubpp для указания количества элементов в стеке. См. "Variable-length Parameter Lists" в perlxs.

I32  items
ix

Переменная, настраиваемая xsubpp для указания того, какой из псевдонимов XSUB был использован для его вызова. См. "The ALIAS: Keyword" в perlxs.

I32  ix
MY_CXT

Описание в perlxs.

MY_CXT_CLONE

Описание в perlxs.

MY_CXT_INIT

Описание в perlxs.

pMY_CXT

Описание в perlxs.

_pMY_CXT

Описание в perlxs.

pMY_CXT_

Описание в perlxs.

RETVAL

Переменная, настраиваемая xsubpp для хранения возвращаемого значения XSUB. Она всегда имеет правильный тип для XSUB. См. "The RETVAL Variable" в perlxs.

type  RETVAL
ST

Используется для доступа к элементам стека XSUB.

SV*  ST(int ix)
START_MY_CXT

Описание в perlxs.

THIS

Переменная, настраиваемая xsubpp для обозначения объекта в C++ XSUB. Она всегда имеет правильный тип для C++ объекта. См. "CLASS" и "Using XS With C++" в perlxs.

type  THIS
UNDERBAR

SV*, соответствующий переменной $_. Работает даже при наличии лексической переменной $_ в области видимости.

XS

Макрос для объявления XSUB и его списка C-параметров. Обрабатывается xsubpp. Это то же самое, что использование более явного макроса XS_EXTERNAL; последний предпочтительнее.

XS_EXTERNAL

Макрос для объявления XSUB и его списка C-параметров, явно экспортирующий символы.

XS_INTERNAL

Макрос для объявления XSUB и его списка C-параметров без экспорта символов. Обрабатывается xsubpp и обычно предпочтительнее, чем ненужный экспорт символов XSUB.

XSPROTO

Макрос, используемый "XS_INTERNAL" и "XS_EXTERNAL" для объявления прототипа функции. Вероятно, вам не следует использовать его напрямую.

Элементы без документации

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

Если вы считаете, что вам нужно использовать одну из этих функций, отправьте сообщение по электронной почте на адрес perl5-porters@perl.org. Возможно, есть веская причина, по которой функция не задокументирована, и её следует удалить из этого списка; или, возможно, просто никто не удосужился её задокументировать. В последнем случае вас попросят отправить исправление с документацией функции. После принятия вашего исправления это будет означать, что интерфейс стабилен (если не указано иное) и может использоваться вами.

clone_params_del  newANONATTRSUB  newAVREF  newSVREF       
clone_params_new  newANONHASH     newCVREF  resume_compcv  
do_open           newANONLIST     newGVREF  sv_dup         
do_openn          newANONSUB      newHVREF  sv_dup_inc

Далее перечислены элементы API, помеченные как экспериментальные. Использование одного из них еще более рискованно, чем просто незадокументированных. Они указаны здесь, потому что должны быть где-то перечислены (чтобы их существование не потерялось), и это лучшее место для этого.

apply_attrs_string        hv_store_flags       thread_locale_init
gv_fetchmethod_pv_flags   leave_adjust_stacks  thread_locale_term
gv_fetchmethod_pvn_flags  newXS_flags          
gv_fetchmethod_sv_flags   savetmps

Наконец, устаревшие незадокументированные элементы API. Не используйте их для нового кода; удалите все вхождения всех из существующего кода.

В настоящее время элементов этого типа нет

АВТОРЫ

До мая 1997 года этот документ поддерживался Джеффом Окамото <okamoto@corp.hp.com>. Сейчас он поддерживается в составе самого Perl.

С большой помощью и предложениями от Дина Роэриха, Малькольма Бити, Андреаса Кёнига, Пола Хадсона, Ильи Захаревича, Пола Маркесса, Нила Боуэрса, Мэттью Грина, Тима Банса, Паука Бордмана, Ульриха Пфейфера, Стивена МакКаманта и Гурусами Сарати.

Список API первоначально составлен Дином Роэрихом <roehrich@cray.com>.

Обновлен для автоматического генерирования из комментариев в исходном коде Беньямином Штулем.

См. также

config.h, perlapio, perlcall, perlclib, perlembed, perlfilter, perlguts, perlhacktips, perlintern, perlinterp, perliol, perlmroapi, perlreapi, perlreguts, perlxs

© 1993–2023 Larry Wall and others
Licensed under the GNU General Public License version 1 or later, or the Artistic License.
The Perl logo is a trademark of the Perl Foundation.
https://perldoc.perl.org/5.38.0/perlapi

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API