perlapi

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• ОПИСАНИЕ
• Обработка AV
• Функции обратного вызова
• Приведение типов
• Изменение регистра символов
• Классификация символов
• Информация о компиляторе и препроцессоре
• Директивы компилятора
• Временные крючки области действия
• Конкурентность
• COP и хэши подсказок
• Пользовательские операторы
• Обработка CV
• Отладка
• Функции отображения
• Встраивание, потоки и клонирование интерпретатора
• Errno
• Макросы обработки исключений (простые)
• Значения конфигурации файловой системы
• Числа с плавающей точкой
• Общая настройка
  • Список символов возможностей HAS_foo
  • Список символов #include
• Глобальные переменные
• Обработка GV и стеков
• Управление крючками
• Обработка HV
• Ввод/вывод
• Целые числа
• Форматы ввода/вывода
• Интерфейс лексического анализатора
• Локали
• Магия
• Управление памятью
• MRO
• Функции Multicall
• Числовые функции
• Optrees
• Упаковка и распаковка
• Структуры данных с выравниванием
• Доступ к паролям и группам
• Пути к системным командам
• Информация о прототипах
• Функции REGEXP
• Отчёты и форматы
• Сигналы
• Конфигурация сайта
• Значения конфигурации сокетов
• Фильтры исходного кода
• Макросы управления стеком
• Обработка строк
• Флаги SV
• Обработка SV
• Загрязнение
• Время
• Имена typedef
• Поддержка Unicode
• Вспомогательные функции
• Версионирование
• Предупреждения и выход
• 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) (с splice в контексте void, если G_DISCARD присутствует).

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 равно true, вы гарантированно получите реальный 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's $#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_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).

См. "Понимание магии связанных хэшей и массивов" в 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 равно нулю, и переменная не существует, возвращается 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)

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

Эквивалент Perl's wantarray для XSUB-писателя. Возвращает 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");

PL_errgv

Описано в perlcall.

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(void * p)

SAVEFREESV

Описание в perlguts.

SAVEFREESV(SV* sv)

save_hash

Описание в perlguts.

HV*  save_hash(GV* gv)

save_hptr

Описание в perlguts.

void  save_hptr(HV** hptr)

SAVEI8

Описание в perlguts.

SAVEI8(I8 i)

SAVEI32

Описание в perlguts.

SAVEI32(I32 i)

SAVEI16

Описание в perlguts.

SAVEI16(I16 i)

SAVEINT

Описание в perlguts.

SAVEINT(int i)

save_item

Описание в perlguts.

void  save_item(SV* item)

SAVEIV

Описание в perlguts.

SAVEIV(IV i)

save_list

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

Описание в perlguts.

void  save_list(SV** sarg, I32 maxsarg)

SAVELONG

Описание в perlguts.

SAVELONG(long i)

SAVEMORTALIZESV

Описание в perlguts.

SAVEMORTALIZESV(SV* sv)

SAVEPPTR

Описание в perlguts.

SAVEPPTR(char * p)

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;

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

cBOOL

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

bool  cBOOL(bool expr)

I_32

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

I32  I_32(NV what)

INT2PTR

Описание в perlguts.

type  INT2PTR(type, int value)

I_V

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

IV  I_V(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_32

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

U32  U_32(NV what)

U_V

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

UV  U_V(NV what)

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

Perl использует полные отображения Unicode-регистра. Это означает, что преобразование одного символа в другой регистр может привести к последовательности более одного символа. Например, заглавная буква от ß (маленькая буква с острым S) — это последовательность из двух символов SS. Это создаёт некоторые сложности. Строчные буквы всех символов в диапазоне 0..255 — это один символ, и поэтому предоставляется "toLOWER_L1". Но toUPPER_L1 не может существовать, так как не может вернуть правильный результат для всех допустимых входных данных. Вместо этого "toUPPER_uvchr" имеет API, который позволяет вернуть все возможные корректные результаты.) Точно так же не реализованы другие функции, которые не могут обеспечить правильные результаты для всего диапазона возможных входных данных.

toFOLD

toFOLD_A

toFOLD_uvchr

toFOLD_utf8

toFOLD_utf8_safe

Все эти функции возвращают сложенный регистр символа. «Сложенный регистр» — это внутренний регистр для /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 возвращает сложенный регистр любой Unicode-кодовой точки. Результат идентичен результату toFOLD_A для входных кодовых точек ASCII. Сложенный регистр большинства Unicode-кодовых точек совпадает с самим кодовым символом. В этих случаях и для кодовых точек, превышающих максимальное значение Unicode, функция возвращает входную кодовую точку без изменений. Дополнительно она записывает 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_uvchr    (UV cp, U8* s, STRLEN* lenp)
UV  toFOLD_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toFOLD_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)

toLOWER

toLOWER_A

toLOWER_L1

toLOWER_LATIN1

toLOWER_LC

toLOWER_uvchr

toLOWER_utf8

toLOWER_utf8_safe

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

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

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

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

toLOWER_uvchr возвращает строчную версию любого Unicode-символа. Результат совпадает с toLOWER_L1 для входных кодов символов в диапазоне 0..255. Строчная форма большинства Unicode-символов совпадает с самим символом. Для таких символов, а также для символов с кодом выше максимального значения Unicode, функция возвращает входной код символа без изменений. Кроме того, она сохраняет 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_L1       (UV cp)
UV  toLOWER_LATIN1   (UV cp)
UV  toLOWER_LC       (UV cp)
UV  toLOWER_uvchr    (UV cp, U8* s, STRLEN* lenp)
UV  toLOWER_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)

toTITLE

toTITLE_A

toTITLE_uvchr

toTITLE_utf8

toTITLE_utf8_safe

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

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

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

toTITLE_uvchr возвращает заглавные буквы любого Unicode-символа. Результат совпадает с toTITLE_A для символов ASCII. Заглавные буквы большинства Unicode-символов совпадают с самим символом. Для таких символов, а также для символов с кодом выше максимального значения Unicode, функция возвращает входной код символа без изменений. Кроме того, она сохраняет 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_uvchr    (UV cp, U8* s, STRLEN* lenp)
UV  toTITLE_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toTITLE_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)

toUPPER

toUPPER_A

toUPPER_uvchr

toUPPER_utf8

toUPPER_utf8_safe

Все эти функции возвращают прописные буквы символа. Различия заключаются в области их применения и в том, задаётся ли входной параметр как код символа (функции с параметром 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_uvchr    (UV cp, U8* s, STRLEN* lenp)
UV  toUPPER_utf8     (U8* p, U8* e, U8* s, STRLEN* lenp)
UV  toUPPER_utf8_safe(U8* p, U8* e, 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, он использует опубликованные правила Юникода; в противном случае он использует функцию C-библиотеки, которая предоставляет указанную классификацию. Например, isDIGIT_LC() при работе не в UTF-8 локали возвращает результат вызова isdigit(). FALSE всегда возвращается, если вход не помещается в один байт. На некоторых платформах, где функция C-библиотеки известна как дефектная, Perl изменяет свой результат, чтобы соответствовать правилам стандарта POSIX.

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

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

isALPHA

isALPHA_A

isALPHA_L1

isALPHA_uvchr

isALPHA_utf8_safe

isALPHA_utf8

isALPHA_LC

isALPHA_LC_uvchr

isALPHA_LC_utf8_safe

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

bool  isALPHA             (UV ch)
bool  isALPHA_A           (UV ch)
bool  isALPHA_L1          (UV ch)
bool  isALPHA_uvchr       (UV ch)
bool  isALPHA_utf8_safe   (U8 * s, U8 * end)
bool  isALPHA_utf8        (U8 * s, U8 * end)
bool  isALPHA_LC          (UV ch)
bool  isALPHA_LC_uvchr    (UV ch)
bool  isALPHA_LC_utf8_safe(U8 * s, U8 *end)

isALPHANUMERIC

isALPHANUMERIC_A

isALPHANUMERIC_L1

isALPHANUMERIC_uvchr

isALPHANUMERIC_utf8_safe

isALPHANUMERIC_utf8

isALPHANUMERIC_LC

isALPHANUMERIC_LC_uvchr

isALPHANUMERIC_LC_utf8_safe

isALNUMC

isALNUMC_A

isALNUMC_L1

isALNUMC_LC

isALNUMC_LC_uvchr

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

Синоним (не рекомендуется к использованию) — isALNUMC (где суффикс C означает, что это соответствует определению буквенно-цифровых символов языка C). Также существуют варианты isALNUMC_A, isALNUMC_L1 isALNUMC_LC, и isALNUMC_LC_uvchr.

bool  isALPHANUMERIC             (UV ch)
bool  isALPHANUMERIC_A           (UV ch)
bool  isALPHANUMERIC_L1          (UV ch)
bool  isALPHANUMERIC_uvchr       (UV ch)
bool  isALPHANUMERIC_utf8_safe   (U8 * s, U8 * end)
bool  isALPHANUMERIC_utf8        (U8 * s, U8 * end)
bool  isALPHANUMERIC_LC          (UV ch)
bool  isALPHANUMERIC_LC_uvchr    (UV ch)
bool  isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end)
bool  isALNUMC                   (UV ch)
bool  isALNUMC_A                 (UV ch)
bool  isALNUMC_L1                (UV ch)
bool  isALNUMC_LC                (UV ch)
bool  isALNUMC_LC_uvchr          (UV ch)

isASCII

isASCII_A

isASCII_L1

isASCII_uvchr

isASCII_utf8_safe

isASCII_utf8

isASCII_LC

isASCII_LC_uvchr

isASCII_LC_utf8_safe

Возвращает булево значение, указывающее, является ли указанный символ одним из 128 символов набора символов ASCII, аналогично m/[[:ascii:]]/. На платформах, не поддерживающих ASCII, она возвращает TRUE, если этот символ соответствует символу 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_L1          (UV ch)
bool  isASCII_uvchr       (UV ch)
bool  isASCII_utf8_safe   (U8 * s, U8 * end)
bool  isASCII_utf8        (U8 * s, U8 * end)
bool  isASCII_LC          (UV ch)
bool  isASCII_LC_uvchr    (UV ch)
bool  isASCII_LC_utf8_safe(U8 * s, U8 *end)

isBLANK

isBLANK_A

isBLANK_L1

isBLANK_uvchr

isBLANK_utf8_safe

isBLANK_utf8

isBLANK_LC

isBLANK_LC_uvchr

isBLANK_LC_utf8_safe

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

bool  isBLANK             (UV ch)
bool  isBLANK_A           (UV ch)
bool  isBLANK_L1          (UV ch)
bool  isBLANK_uvchr       (UV ch)
bool  isBLANK_utf8_safe   (U8 * s, U8 * end)
bool  isBLANK_utf8        (U8 * s, U8 * end)
bool  isBLANK_LC          (UV ch)
bool  isBLANK_LC_uvchr    (UV ch)
bool  isBLANK_LC_utf8_safe(U8 * s, U8 *end)

isCNTRL

isCNTRL_A

isCNTRL_L1

isCNTRL_uvchr

isCNTRL_utf8_safe

isCNTRL_utf8

isCNTRL_LC

isCNTRL_LC_uvchr

isCNTRL_LC_utf8_safe

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

bool  isCNTRL             (UV ch)
bool  isCNTRL_A           (UV ch)
bool  isCNTRL_L1          (UV ch)
bool  isCNTRL_uvchr       (UV ch)
bool  isCNTRL_utf8_safe   (U8 * s, U8 * end)
bool  isCNTRL_utf8        (U8 * s, U8 * end)
bool  isCNTRL_LC          (UV ch)
bool  isCNTRL_LC_uvchr    (UV ch)
bool  isCNTRL_LC_utf8_safe(U8 * s, U8 *end)

isDIGIT

isDIGIT_A

isDIGIT_L1

isDIGIT_uvchr

isDIGIT_utf8_safe

isDIGIT_utf8

isDIGIT_LC

isDIGIT_LC_uvchr

isDIGIT_LC_utf8_safe

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

bool  isDIGIT             (UV ch)
bool  isDIGIT_A           (UV ch)
bool  isDIGIT_L1          (UV ch)
bool  isDIGIT_uvchr       (UV ch)
bool  isDIGIT_utf8_safe   (U8 * s, U8 * end)
bool  isDIGIT_utf8        (U8 * s, U8 * end)
bool  isDIGIT_LC          (UV ch)
bool  isDIGIT_LC_uvchr    (UV ch)
bool  isDIGIT_LC_utf8_safe(U8 * s, U8 *end)

isGRAPH

isGRAPH_A

isGRAPH_L1

isGRAPH_uvchr

isGRAPH_utf8_safe

isGRAPH_utf8

isGRAPH_LC

isGRAPH_LC_uvchr

isGRAPH_LC_utf8_safe

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

bool  isGRAPH             (UV ch)
bool  isGRAPH_A           (UV ch)
bool  isGRAPH_L1          (UV ch)
bool  isGRAPH_uvchr       (UV ch)
bool  isGRAPH_utf8_safe   (U8 * s, U8 * end)
bool  isGRAPH_utf8        (U8 * s, U8 * end)
bool  isGRAPH_LC          (UV ch)
bool  isGRAPH_LC_uvchr    (UV ch)
bool  isGRAPH_LC_utf8_safe(U8 * s, U8 *end)

isIDCONT

isIDCONT_A

isIDCONT_L1

isIDCONT_uvchr

isIDCONT_utf8_safe

isIDCONT_utf8

isIDCONT_LC

isIDCONT_LC_uvchr

isIDCONT_LC_utf8_safe

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

bool  isIDCONT             (UV ch)
bool  isIDCONT_A           (UV ch)
bool  isIDCONT_L1          (UV ch)
bool  isIDCONT_uvchr       (UV ch)
bool  isIDCONT_utf8_safe   (U8 * s, U8 * end)
bool  isIDCONT_utf8        (U8 * s, U8 * end)
bool  isIDCONT_LC          (UV ch)
bool  isIDCONT_LC_uvchr    (UV ch)
bool  isIDCONT_LC_utf8_safe(U8 * s, U8 *end)

isIDFIRST

isIDFIRST_A

isIDFIRST_L1

isIDFIRST_uvchr

isIDFIRST_utf8_safe

isIDFIRST_utf8

isIDFIRST_LC

isIDFIRST_LC_uvchr

isIDFIRST_LC_utf8_safe

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

bool  isIDFIRST             (UV ch)
bool  isIDFIRST_A           (UV ch)
bool  isIDFIRST_L1          (UV ch)
bool  isIDFIRST_uvchr       (UV ch)
bool  isIDFIRST_utf8_safe   (U8 * s, U8 * end)
bool  isIDFIRST_utf8        (U8 * s, U8 * end)
bool  isIDFIRST_LC          (UV ch)
bool  isIDFIRST_LC_uvchr    (UV ch)
bool  isIDFIRST_LC_utf8_safe(U8 * s, U8 *end)

isLOWER

isLOWER_A

isLOWER_L1

isLOWER_uvchr

isLOWER_utf8_safe

isLOWER_utf8

isLOWER_LC

isLOWER_LC_uvchr

isLOWER_LC_utf8_safe

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

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

isOCTAL

isOCTAL_A

isOCTAL_L1

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

bool  isOCTAL(UV ch)

isPRINT

isPRINT_A

isPRINT_L1

isPRINT_uvchr

isPRINT_utf8_safe

isPRINT_utf8

isPRINT_LC

isPRINT_LC_uvchr

isPRINT_LC_utf8_safe

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

bool  isPRINT             (UV ch)
bool  isPRINT_A           (UV ch)
bool  isPRINT_L1          (UV ch)
bool  isPRINT_uvchr       (UV ch)
bool  isPRINT_utf8_safe   (U8 * s, U8 * end)
bool  isPRINT_utf8        (U8 * s, U8 * end)
bool  isPRINT_LC          (UV ch)
bool  isPRINT_LC_uvchr    (UV ch)
bool  isPRINT_LC_utf8_safe(U8 * s, U8 *end)

isPSXSPC

isPSXSPC_A

isPSXSPC_L1

isPSXSPC_uvchr

isPSXSPC_utf8_safe

isPSXSPC_utf8

isPSXSPC_LC

isPSXSPC_LC_uvchr

isPSXSPC_LC_utf8_safe

(сокращенно 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_L1          (UV ch)
bool  isPSXSPC_uvchr       (UV ch)
bool  isPSXSPC_utf8_safe   (U8 * s, U8 * end)
bool  isPSXSPC_utf8        (U8 * s, U8 * end)
bool  isPSXSPC_LC          (UV ch)
bool  isPSXSPC_LC_uvchr    (UV ch)
bool  isPSXSPC_LC_utf8_safe(U8 * s, U8 *end)

isPUNCT

isPUNCT_A

isPUNCT_L1

isPUNCT_uvchr

isPUNCT_utf8_safe

isPUNCT_utf8

isPUNCT_LC

isPUNCT_LC_uvchr

isPUNCT_LC_utf8_safe

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

bool  isPUNCT             (UV ch)
bool  isPUNCT_A           (UV ch)
bool  isPUNCT_L1          (UV ch)
bool  isPUNCT_uvchr       (UV ch)
bool  isPUNCT_utf8_safe   (U8 * s, U8 * end)
bool  isPUNCT_utf8        (U8 * s, U8 * end)
bool  isPUNCT_LC          (UV ch)
bool  isPUNCT_LC_uvchr    (UV ch)
bool  isPUNCT_LC_utf8_safe(U8 * s, U8 *end)

isSPACE

isSPACE_A

isSPACE_L1

isSPACE_uvchr

isSPACE_utf8_safe

isSPACE_utf8

isSPACE_LC

isSPACE_LC_uvchr

isSPACE_LC_utf8_safe

Возвращает булево значение, указывающее, является ли указанный символ символом пробела. Это аналогично тому, что 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_L1          (UV ch)
bool  isSPACE_uvchr       (UV ch)
bool  isSPACE_utf8_safe   (U8 * s, U8 * end)
bool  isSPACE_utf8        (U8 * s, U8 * end)
bool  isSPACE_LC          (UV ch)
bool  isSPACE_LC_uvchr    (UV ch)
bool  isSPACE_LC_utf8_safe(U8 * s, U8 *end)

isUPPER

isUPPER_A

isUPPER_L1

isUPPER_uvchr

isUPPER_utf8_safe

isUPPER_utf8

isUPPER_LC

isUPPER_LC_uvchr

isUPPER_LC_utf8_safe

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

bool  isUPPER             (UV ch)
bool  isUPPER_A           (UV ch)
bool  isUPPER_L1          (UV ch)
bool  isUPPER_uvchr       (UV ch)
bool  isUPPER_utf8_safe   (U8 * s, U8 * end)
bool  isUPPER_utf8        (U8 * s, U8 * end)
bool  isUPPER_LC          (UV ch)
bool  isUPPER_LC_uvchr    (UV ch)
bool  isUPPER_LC_utf8_safe(U8 * s, U8 *end)

isWORDCHAR

isWORDCHAR_A

isWORDCHAR_L1

isWORDCHAR_uvchr

isWORDCHAR_utf8_safe

isWORDCHAR_utf8

isWORDCHAR_LC

isWORDCHAR_LC_uvchr

isWORDCHAR_LC_utf8_safe

isALNUM

isALNUM_A

isALNUM_LC

isALNUM_LC_uvchr

Возвращает булево значение, указывающее, является ли указанный символ символом слова, аналогично тому, что m/\w/ и m/[[:word:]]/ соответствуют в регулярном выражении. Символ слова — это буквенный символ, десятичная цифра, соединительный пунктуационный символ (например, нижнее подчёркивание) или символ «метки», который прикрепляется к одному из них (например, некоторые типы диакритики). isALNUM() — синоним, предоставленный для обратной совместимости, хотя символ слова включает в себя больше, чем стандартное значение символа в языке C. См. начало этого раздела «Классификация символов» для объяснения вариантов. 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_L1          (UV ch)
bool  isWORDCHAR_uvchr       (UV ch)
bool  isWORDCHAR_utf8_safe   (U8 * s, U8 * end)
bool  isWORDCHAR_utf8        (U8 * s, U8 * end)
bool  isWORDCHAR_LC          (UV ch)
bool  isWORDCHAR_LC_uvchr    (UV ch)
bool  isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end)
bool  isALNUM                (UV ch)
bool  isALNUM_A              (UV ch)
bool  isALNUM_LC             (UV ch)
bool  isALNUM_LC_uvchr       (UV ch)

isXDIGIT

isXDIGIT_A

isXDIGIT_L1

isXDIGIT_uvchr

isXDIGIT_utf8_safe

isXDIGIT_utf8

isXDIGIT_LC

isXDIGIT_LC_uvchr

isXDIGIT_LC_utf8_safe

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

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

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

CPPLAST

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

CPPMINUS

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

CPPRUN

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

CPPSTDIN

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

HASATTRIBUTE_ALWAYS_INLINE

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

HASATTRIBUTE_DEPRECATED

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

HASATTRIBUTE_FORMAT

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

HASATTRIBUTE_NONNULL

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

HASATTRIBUTE_NORETURN

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

HASATTRIBUTE_PURE

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

HASATTRIBUTE_UNUSED

Можем ли мы обработать атрибут 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.

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

ASSUME

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

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);

PERL_USE_GCC_BRACE_GROUPS

Если это значение препроцессора C определено, это означает, что разрешено использование расширения GCC brace groups. Это расширение в форме

({ statement ... })

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

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

#ifdef PERL_USE_GCC_BRACE_GROUPS
  ...
#else
  ...
#endif

START_EXTERN_C

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

START_EXTERN_C

STATIC

Описано в perlguts.

STMT_START

STMT_END

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

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

Обратите внимание, что вы не можете вернуть значение из них, что ограничивает их полезность. Но см. "PERL_USE_GCC_BRACE_GROUPS".

UNLIKELY

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

UNLIKELY(bool expr)

__ASSERT_

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

__ASSERT_(bool expr)

Обработка областей компиляции во время компиляции

BhkDISABLE

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

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

void  BhkDISABLE(BHK *hk, which)

BhkENABLE

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

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

void  BhkENABLE(BHK *hk, which)

BhkENTRY_set

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

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

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

blockhook_register

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

Зарегистрировать набор хуков, которые будут вызываться при изменении лексического контекста Perl во время компиляции. См. "Обработка областей компиляции во время компиляции" в 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_PTHREADS_API

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

OLD_PTHREAD_CREATE_JOINABLE

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

PERL_IMPLICIT_CONTEXT

Описание в perlguts.

pTHX

Описание в perlguts.

pTHX_

Описание в perlguts.

SCHED_YIELD

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

COPs и хэши подсказок

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)

CopFILEGV

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

GV *  CopFILEGV(const COP * c)

CopFILEGV_set

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

void  CopFILEGV_set(COP * c, GV * gv)

CopFILE_set

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

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

CopFILESV

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

SV *  CopFILESV(const COP * c)

cophh_2hv

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

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

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

cophh_copy

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

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

COPHH *  cophh_copy(COPHH *cophh)

cophh_delete_pvn

cophh_delete_pv

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_pvn(COPHH *cophh, const char *key,
                          STRLEN keylen, U32 hash, U32 flags)
COPHH *  cophh_delete_pv (COPHH *cophh, const char *key, 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_pvn

cophh_fetch_pv

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_pvn(const COPHH *cophh, const char *key,
                      STRLEN keylen, U32 hash, U32 flags)
SV *  cophh_fetch_pv (const COPHH *cophh, const char *key,
                      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_new_empty

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

Создаёт и возвращает новый хеш cop hints, не содержащий записей.

COPHH *  cophh_new_empty()

cophh_store_pvn

cophh_store_pv

cophh_store_pvs

cophh_store_sv

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

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

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

Формы различаются тем, как задаётся ключ. Во всех формах ключ указывается через 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_pvn(COPHH *cophh, const char *key,
                         STRLEN keylen, U32 hash, SV *value,
                         U32 flags)
COPHH *  cophh_store_pv (COPHH *cophh, const char *key, 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_2hv

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

HV *  cop_hints_2hv(const COP *cop, U32 flags)

cop_hints_exists_pvn

cop_hints_exists_pv

cop_hints_exists_pvs

cop_hints_exists_sv

Эти функции ищут запись подсказки в cop 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_pvn(const COP *cop, const char *key,
                           STRLEN keylen, U32 hash, U32 flags)
bool  cop_hints_exists_pv (const COP *cop, const char *key,
                           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_pvn

cop_hints_fetch_pv

cop_hints_fetch_pvs

cop_hints_fetch_sv

Эти функции ищут запись подсказки в cop 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_pvn(const COP *cop, const char *key,
                          STRLEN keylen, U32 hash, U32 flags)
SV *  cop_hints_fetch_pv (const COP *cop, const char *key,
                          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)

CopLABEL

CopLABEL_len

CopLABEL_len_flags

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

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

STRLEN  CopLINE(const COP * c)

CopSTASH

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

HV *  CopSTASH(const COP * c)

CopSTASH_eq

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

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

CopSTASHPV

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

char *  CopSTASHPV(const COP * c)

CopSTASHPV_set

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

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

CopSTASH_set

Устанавливает stash, связанный с 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

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

custom_op_desc

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

Возвращает описание заданного оператора пользовательского определения. Раньше он использовался макросом OP_DESC, но больше не используется: он сохраняется только для совместимости и не должен использоваться.

const char *  custom_op_desc(const OP *o)

custom_op_name

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

Возвращает имя заданного оператора пользовательского определения. Раньше он использовался макросом OP_NAME, но больше не используется: он сохраняется только для совместимости и не должен использоваться.

const char *  custom_op_name(const OP *o)

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, which)

XopENABLE

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

void  XopENABLE(XOP *xop, which)

XopENTRY

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

XopENTRY(XOP *xop, which)

XopENTRYCUSTOM

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

XopENTRYCUSTOM(const OP *o, which)

XopENTRY_set

Установить член структуры XOP. which — это маркер языка C++, указывающий, какой элемент нужно установить. Подробности об доступных членах и их использовании см. в разделе "Пользовательские операторы" в perlguts. Данный макрос вычисляет свой аргумент более одного раза.

void  XopENTRY_set(XOP *xop, 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)

CvDEPTH

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

I32 *  CvDEPTH(const CV * const sv)

CvGV

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

GV *  CvGV(CV *sv)

CvSTASH

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

Это также имеет специальное применение для XS 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_cvs

get_cvn_flags

Эти функции возвращают 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_cvs() устарела.

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

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

Nullcv

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

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

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

SvAMAGIC_off

Указывает, что у sv отключена перегрузка (активная магия).

void  SvAMAGIC_off(SV *sv)

SvAMAGIC_on

Указывает, что у sv включена перегрузка (активная магия).

void  SvAMAGIC_on(SV *sv)

Отладка

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

Выводит весь оп-дерево текущей программы, начиная с PL_main_root до STDERR. Также выводит оп-деревья всех видимых подпрограмм в 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

Выводит оп-деревья всех видимых подпрограмм в 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
...

Поля разделены табуляцией. Первый столбец — глубина (ноль — самый внутренний кадр, не пропущенный). В hex:offset шестнадцатеричное значение — это адрес программы в S_parse_body, а :offset (может отсутствовать) указывает, насколько глубоко в 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.

magic_dump

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

void  magic_dump(const MAGIC *mg)

op_class

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

OPclass  op_class(const OP *o)

op_dump

Выводит оп-дерево, начиная с 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.

void  sv_dump(SV* sv)

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.

Если flags содержит 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_FIRSTCHAR установлено, будет экранирован только первый символ строки, независимо от max. Если вывод должен быть в шестнадцатеричном формате, он будет возвращен как обычная шестнадцатеричная последовательность. Таким образом, вывод будет либо одиночным символом, либо восьмеричной последовательностью экранирования, либо специальной последовательностью экранирования, такой как \n, или шестнадцатеричным значением.

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

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

char*  pv_escape(SV *dsv, char const * const str,
                 const STRLEN count, const STRLEN max,
                 STRLEN * const escaped, const 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()

find_rundefsvoffset

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

До удаления лексического $_ этот функция находила позицию лексической $_ в стеке текущей функции и возвращала смещение в текущем стеке или NOT_IN_PAD.

Теперь она всегда возвращает NOT_IN_PAD.

PADOFFSET  find_rundefsvoffset()

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

newPADNAMELIST

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

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

PADNAMELIST *  newPADNAMELIST(size_t max)

newPADNAMEouter

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

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

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 является экспериментальным и может быть изменён или удалён без предварительного уведомления.

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

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_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, или может быть равна null для отказа от такой настройки.

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

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

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

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

По историческим причинам, ненулевое возвращаемое значение также пытается быть подходящим значением для передачи в функцию библиотеки C exit (или для возврата из main), чтобы служить в качестве кода завершения, указывающего на характер завершения инициализации. Однако это не переносимо из-за различных соглашений о кодах завершения. Сохраняется историческая ошибка: если встроенная функция Perl exit вызывается во время выполнения этой функции с типом выхода, подразумевающим нулевой код выхода в соответствии с соглашениями операционной системы хоста, то эта функция возвращает ноль вместо ненулевого значения. Эта ошибка [perl #2754] приводит к вызову perl_run (и, следовательно, к выполнению INIT блоков и основной программы) несмотря на вызов exit. Она сохранена, потому что популярный модуль-установщик полагается на неё и требует времени на исправление. Эта проблема [perl #132577], а исходная ошибка должна быть исправлена в Perl 5.30.

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 при выходе:

• PERL_EXIT_DESTRUCT_END

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

• PERL_EXIT_ABORT

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

• PERL_EXIT_WARN

  Выводить предупреждения при выходе.

• PERL_EXIT_EXPECTED

  Устанавливается оператором "exit" в 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

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)

Errno

sv_string_from_errnum

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

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

Сообщение будет взято из того языка, который использовался бы $!, и будет закодировано в SV так, как это делалось бы $!. Подробности этого процесса могут измениться в будущем. В настоящее время сообщение берётся из C-локалей по умолчанию (обычно генерируется английское сообщение), и из выбранной локали во время действия псевдонима 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

Вводит блок 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

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

HAS_DUP2

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

HAS_DUP3

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

HAS_FAST_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_OPEN3

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

HAS_OPENAT

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

HAS_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 для опроса активных дескрипторов файлов. Если используется поле тайм-аута, может потребоваться включить 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) , а не из 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_LVALUE

Этот символ определен, если макрос FILE_ptr может использоваться как 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_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 доступна для классификации значений типа double. Доступна, например, в 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 доступна для проверки, является ли значение типа double конечным (не бесконечность и не NaN).

HAS_FINITEL

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

HAS_FPCLASS

Этот символ, если определен, указывает, что функция fpclass доступна для классификации значений типа double. Доступна, например, в 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_FPCLASSIFY

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

FP_NORMAL     Normalized
FP_ZERO       Zero
FP_INFINITE   Infinity
FP_SUBNORMAL  Denormalized
FP_NAN        NaN

HAS_FPCLASSL

Этот символ, если определен, указывает, что функция fpclassl доступна для классификации значений типа long double. Доступна, например, в 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_FPGETROUND

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

HAS_FP_CLASS

Этот символ, если определен, указывает, что функция fp_class доступна для классификации значений типа double. Доступна, например, в 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_FP_CLASSIFY

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

FP_NORMAL     Normalized
FP_ZERO       Zero
FP_INFINITE   Infinity
FP_SUBNORMAL  Denormalized
FP_NAN        NaN

HAS_FP_CLASSL

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

HAS_FREXPL

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

HAS_ILOGB

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

HAS_ISFINITE

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

HAS_ISFINITEL

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

HAS_ISINF

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

HAS_ISINFL

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

HAS_ISNAN

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

HAS_ISNANL

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

HAS_ISNORMAL

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

HAS_J0

Если этот символ определён, то C-программа может использовать функцию j0() для вычисления функции Бесселя первого рода нулевого порядка от двойного значения.

HAS_J0L

Если этот символ определён, то C-программа может использовать функцию j0l() для вычисления функции Бесселя первого рода нулевого порядка от длинного двойного значения.

HAS_LDBL_DIG

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

HAS_LDEXPL

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

HAS_LLRINT

Если этот символ определён, то функция llrint доступна для возвращения целого 64-битного значения, ближайшего к двойному значению (согласно текущему режиму округления).

HAS_LLRINTL

Если этот символ определён, то функция llrintl доступна для возвращения целого 64-битного значения, ближайшего к значению с длинной двойной точностью (согласно текущему режиму округления).

HAS_LLROUNDL

Если этот символ определён, то функция llroundl доступна для возвращения ближайшего 64-битного целого значения к значению с длинной двойной точностью, удаляясь от нуля.

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 доступна для возвращения дробной части от операции деления.

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 доступна для проверки, являются ли два двойных значения неупорядоченными (эффективно: является ли хотя бы одно из них 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

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

LONG_DOUBLE_STYLE_IEEE

Если этот символ определён, то длинное двойное значение соответствует какому-либо из форматов IEEE 754: LONG_DOUBLE_STYLE_IEEE_STD, LONG_DOUBLE_STYLE_IEEE_EXTENDED, LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE.

LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE

Если этот символ определён, то длинное двойное значение — 128-битное число двойной точности.

LONG_DOUBLE_STYLE_IEEE_EXTENDED

Если этот символ определён, то длинное двойное значение — 80-битный расширенный формат IEEE 754. Заметьте, что несмотря на "расширенный", он меньше, чем "стандартный", так как это расширение двойной точности.

LONG_DOUBLE_STYLE_IEEE_STD

Если этот символ определён, то длинное двойное значение — 128-битный стандартный формат IEEE 754.

LONG_DOUBLE_STYLE_VAX

Если этот символ определён, то длинное двойное значение соответствует 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, используемый для Perl NV.

NV_ZERO_IS_ALLBITS_ZERO

Если этот символ определён, то переменная типа NVTYPE хранит 0.0 в памяти как все биты ноль.

Общие настройки

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

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 без ошибок или предупреждений принимает битовые поля struct bitfields, объявленные с размером, отличным от простого '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, который в конечном итоге будет '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, как правило, более надёжны.

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), особенно на многих малозначащих системах, последние выполняется. Это полезно только если у вас есть 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_EXP2, HAS_EXPM1, 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_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_INETNTOP, HAS_INETPTON, HAS_INET_ATON, HAS_IPV6_MREQ, HAS_IPV6_MREQ_SOURCE, HAS_IP_MREQ, HAS_IP_MREQ_SOURCE, HAS_ISASCII, HAS_ISBLANK, HAS_ISLESS, HAS_KILLPG, HAS_LCHOWN, HAS_LINK, HAS_LINKAT, HAS_LLROUND, HAS_LOCKF, HAS_LOG1P, HAS_LOG2, HAS_LOGB, 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_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_SYSTEM, HAS_SYS_ERRLIST, 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_WAIT4, HAS_WAITPID, HAS_WCRTOMB, HAS_WCSCMP, HAS_WCSTOMBS, HAS_WCSXFRM, HAS_WCTOMB, HAS_WRITEV, HAS__FWALK, 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_SRAND48_R, HAS_SRANDOM_R, HAS_STRERROR_R, HAS_TMPNAM_R, HAS_TTYNAME_R,

#ifdef HAS_STRNLEN
  use strnlen()
#else
  use an alternative implementation
#endif

#ifdef I_WCHAR
  #include <wchar.h>
#endif

И, возможности реентера:

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_SRAND48_R, HAS_SRANDOM_R, HAS_STRERROR_R, HAS_TMPNAM_R, HAS_TTYNAME_R

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

#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_NETINET_IN, I_NETINET_TCP, I_NET_ERRNO, I_PROT, I_PWD, I_RPCSVC_DBM, I_SGTTY, I_SHADOW, I_STDBOOL, I_STDINT, I_SUNMATH, I_SYSLOG, I_SYSMODE, I_SYSUIO, I_SYSUTSNAME, I_SYS_ACCESS, I_SYS_IOCTL, I_SYS_MOUNT, I_SYS_PARAM, I_SYS_POLL, I_SYS_SECURITY, I_SYS_SELECT, I_SYS_STAT, I_SYS_STATVFS, I_SYS_TIME, I_SYS_TIMES, I_SYS_TIME_KERNEL, I_SYS_TYPES, I_SYS_UN, 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

Массив, индексированный по коду операции, функций, которые будут вызываться на фазе «проверки» построения дерева optree во время компиляции Perl-кода. Для большинства (но не всех) типов операторов, после того, как оператор был первоначально построен и заполнен операторами-потомками, он будет отфильтрован через функцию проверки, на которую ссылается соответствующий элемент этого массива. Новый оператор передается в качестве единственного аргумента функции проверки, а функция проверки возвращает завершённый оператор. Функция проверки может (как следует из названия) проверить оператор на валидность и сигнализировать об ошибках. Она также может инициализировать или изменить части операторов, или выполнить более радикальную операцию, такую как добавление или удаление операторов-потомков, или даже выбросить оператор и вернуть на его место другой оператор.

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

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

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 — это структура, которая соответствует перловому типуглобу, например, *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

Выполните перегрузку разыменования (active magic) для 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_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*  gv_HVadd(GV *gv)
GV*  gv_IOadd(GV* gv)
GV*  gv_SVadd(GV *gv)

gv_const_sv

Если gv — это типглоб, чей субрутинный записной элемент — это константный суб, подходящий для встраивания, или gv — это заполнитель ссылки, который будет повышен до такого типаглоба, то возвращает значение, возвращаемое суб. В противном случае возвращает NULL.

SV*  gv_const_sv(GV* gv)

GvCV

Возвращает CV из GV.

CV*  GvCV(GV* gv)

gv_fetchfile

gv_fetchfile_flags

Эти функции возвращают глобал дебаггера для файла (скомпилированного Perl), имя которого задано параметром name.

В настоящее время между этими функциями есть ровно два отличия.

Параметр name для gv_fetchfile — это строка C, означающая, что она имеет нулевое завершение; в то время как параметр 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_pvn", но без параметра флагов.

GV*  gv_fetchmeth(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_autoload

Это старый формат "gv_fetchmeth_pvn_autoload", который не имеет параметра флагов.

GV*  gv_fetchmeth_autoload(HV* stash, const char* name,
                           STRLEN len, I32 level)

gv_fetchmeth_pv

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

GV*  gv_fetchmeth_pv(HV* stash, const char* name, I32 level,
                     U32 flags)

gv_fetchmeth_pvn

Возвращает типглоб с заданным name и определённой подпрограммой или NULL. Типглоб находится в заданном stash, или в стеках, доступных через @ISA и UNIVERSAL::.

Аргумент level должен быть либо 0, либо -1. Если level==0, как побочный эффект, создаёт типглоб с заданным name в заданном stash, который в случае успеха содержит псевдоним для подпрограммы, и настраивает кеширование для этого типаглоба.

Единственные существенные значения для flags — GV_SUPER, GV_NOUNIVERSAL, и SVf_UTF8.

GV_SUPER указывает, что мы хотим найти метод в суперклассах stash.

GV_NOUNIVERSAL указывает, что мы не хотим искать метод в стеке, доступном через UNIVERSAL::.

Возвращаемый GV из gv_fetchmeth может быть элементом кэша метода, который не виден коду Perl. Поэтому при вызове call_sv, не следует использовать GV напрямую; вместо этого следует использовать CV метода, который можно получить из GV с помощью макроса GvCV.

GV*  gv_fetchmeth_pvn(HV* stash, const char* name, STRLEN len,
                      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)

gv_fetchmeth_pv_autoload

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

GV*  gv_fetchmeth_pv_autoload(HV* stash, const char* name,
                              I32 level, U32 flags)

gv_fetchmeth_sv

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

GV*  gv_fetchmeth_sv(HV* stash, SV* namesv, I32 level, U32 flags)

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)

gv_fullname3

gv_fullname4

gv_efullname3

gv_efullname4

Поместите полное имя пакета gv в sv. Формы gv_e* вместо этого возвращают эффективное имя пакета (см. "HvENAME").

Если prefix не равно NULL, оно рассматривается как строка C, завершённая нулём, и хранимое имя будет предваряться ей.

Другое отличие между функциями заключается в том, что формы *4 имеют дополнительный параметр keepmain. Если true, начальное main:: в имени сохраняется; если false, оно удаляется. В формах *3 оно всегда сохраняется.

void  gv_fullname3 (SV* sv, const GV* gv, const char* prefix)
void  gv_fullname4 (SV* sv, const GV* gv, const char* prefix,
                    bool keepmain)
void  gv_efullname3(SV* sv, const GV* gv, const char* prefix)
void  gv_efullname4(SV* sv, const GV* gv, const char* prefix,
                    bool keepmain)

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_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_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)

Манипуляции с хуками

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

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 представляет собой перловский массив. Она состоит в основном из массива указателей, каждый из которых указывает на связанный список структур HE. Массив индексируется по функции хэширования ключа, поэтому каждый связанный список представляет все записи хеша с одинаковым значением хэша. Каждый HE содержит указатель на фактическое значение плюс указатель на структуру HEK, которая содержит ключ и значение хэша.

get_hv

Возвращает HV для указанного перловского массива. flags передаются в gv_fetchpv. Если GV_ADD установлено, и перловая переменная не существует, она будет создана. Если flags равно нулю, и переменная не существует, то возвращается 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 может быть typedef для 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

Очищает все заполнительные ключи из хеша. Если ограниченный массив имеет ключи, помеченные как только для чтения, а ключ впоследствии удаляется, ключ фактически не удаляется, а помечается присвоением ему значения &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.

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. Если 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_fetchs

Подобно hv_fetch, но принимает строку-литерал вместо пары строка/длина.

SV**  hv_fetchs(HV* tb, "key", 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)

HvFILL

Возвращает количество используемых хэш-корзин.

Начиная с perl 5.25, эта функция используется только в отладочных целях, и количество используемых хэш-корзин никак не кешируется, поэтому выполнение этой функции может быть дорогостоящим, так как она должна перебирать все корзины в хэше.

STRLEN  HvFILL(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_iternextsv

Выполняет hv_iternext, hv_iterkey, и hv_iterval в одной операции.

SV*  hv_iternextsv(HV *hv, char **key, I32 *retlen)

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_iterval

Возвращает значение из текущей позиции итератора хэша. См. "hv_iterkey".

SV*  hv_iterval(HV *hv, HE *entry)

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)

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

Сохраняет SV в хэше. Ключ хэша задаётся как key, абсолютное значение klen — длина ключа. Если klen отрицательное, ключ предполагается закодированным в UTF-8. Параметр hash — предварительно вычисленное хэш-значение; если оно равно нулю, Perl его вычислит.

Возвращаемое значение будет NULL если операция не удалась или значение не нужно было фактически хранить в хэше (как в случае привязанных хэшей). В противном случае можно обратиться к нему, чтобы получить исходный SV*. Обратите внимание, что вызывающая сторона отвечает за надлежащее увеличение счётчика ссылок для val перед вызовом и уменьшение его, если функция вернула NULL. Фактически успешная hv_store принимает владение одной ссылкой на val. Это обычно то, что вы хотите; у только что созданного SV счётчик ссылок равен 1, поэтому, если весь ваш код лишь создаёт SV и сохраняет их в хэш, hv_store будет владеть единственной ссылкой на новый SV, и вашему коду не нужно будет ничего больше делать, чтобы всё убрать. hv_store не реализован как вызов hv_store_ent, и не создаёт временного SV для ключа, поэтому если данные вашего ключа не в форме SV, используйте hv_store вместо hv_store_ent.

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

SV**  hv_store(HV *hv, const char *key, I32 klen, SV *val,
               U32 hash)

hv_stores

Подобно hv_store, но принимает строку-литерал вместо пары строка/длина и пропускает параметр хэша.

SV**  hv_stores(HV* tb, "key", SV* val)

hv_store_ent

Сохраняет val в хэше. Ключ хэша задаётся как key. Параметр hash — предварительно вычисленное хэш-значение; если оно равно нулю, Perl его вычислит. Возвращаемое значение — созданная новая запись хэша. Оно будет NULL если операция не удалась или значение не нужно было фактически хранить в хэше (как в случае привязанных хэшей). В противном случае содержимое возвращаемого значения можно получить с помощью макросов He?, описанных здесь. Обратите внимание, что вызывающая сторона отвечает за надлежащее увеличение счётчика ссылок для val перед вызовом и уменьшение его, если функция вернула NULL. Фактически успешная hv_store_ent принимает владение одной ссылкой на val. Это обычно то, что вы хотите; у только что созданного SV счётчик ссылок равен 1, поэтому, если весь ваш код лишь создаёт SV и сохраняет их в хэш, hv_store будет владеть единственной ссылкой на новый SV, и вашему коду не нужно будет ничего больше делать, чтобы всё убрать. Обратите внимание, что hv_store_ent только считывает key; в отличие от val, он не принимает владение им, поэтому поддержание правильного счётчика ссылок для key целиком лежит на ответственности вызывающей стороны. Причина, по которой он не принимает владения, заключается в том, что key не используется после возврата этой функции и поэтому может быть освобождён немедленно. hv_store не реализован как вызов hv_store_ent, и не создаёт временный SV для ключа, поэтому если данные вашего ключа не в форме SV, используйте hv_store вместо hv_store_ent.

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

HE*  hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)

hv_undef

Удаляет хэш. Эквивалент XS undef(%hash).

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

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

HV*  PL_modglobal

Ввод/Вывод

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

Библиотечная функция C chsize(3), если доступна, или её Perl-реализация.

I32  my_chsize(int fd, Off_t length)

my_dirfd

Библиотечная функция C dirfd(3), если доступна, или её 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_getc

PerlIO_get_cnt

PerlIO_getpos

PerlIO_get_ptr

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_setlinebuf

PerlIO_setpos

PerlIO_set_ptrcnt

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)
int        PerlIO_getc        (PerlIO *d)
SSize_t    PerlIO_get_cnt     (PerlIO *f)
int        PerlIO_getpos      (PerlIO *f, SV *save)
STDCHAR *  PerlIO_get_ptr     (PerlIO *f)
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_setlinebuf  (PerlIO *f)
int        PerlIO_setpos      (PerlIO *f, SV *saved)
void       PerlIO_set_ptrcnt  (PerlIO *f, STDCHAR *ptr,
                               SSize_t cnt)
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_FUNCS_CAST

Преобразовать указатель func к типу PerlIO_funcs *.

PERLIO_FUNCS_DECL

Объявить ftab как таблицу функций PerlIO, то есть, как PerlIO_funcs.

PERLIO_FUNCS_DECL(PerlIO * ftab)

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

I8

I16

I32

I64

IV

Описано в perlguts.

I32SIZE

Этот символ содержит sizeof(I32).

I32TYPE

Этот символ определяет тип C, используемый для I32 Perl.

I64SIZE

Этот символ содержит sizeof(I64).

I64TYPE

Этот символ определяет тип C, используемый для I64 Perl.

I16SIZE

Этот символ содержит sizeof(I16).

I16TYPE

Этот символ определяет тип C, используемый для I16 Perl.

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 longs, то INTMAX_C(-1) вернёт

-1LL

См. также, например, "INT32_C".

Используйте "IV" для объявления переменных максимального размера, используемого на данной платформе.

INTMAX_C(number)

INTSIZE

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

I8SIZE

Этот символ содержит sizeof(I8).

I8TYPE

Этот символ определяет тип C, используемый для I8 Perl.

IV_MAX

Наибольшее целое число со знаком, которое помещается в IV на данной платформе.

IV  IV_MAX

IV_MIN

Наименьшее целое число со знаком, наиболее удалённое от 0, которое помещается в IV на данной платформе.

IV  IV_MIN

IVSIZE

Этот символ содержит sizeof(IV).

IVTYPE

Этот символ определяет тип C, используемый для IV Perl.

line_t

Тип данных, используемый для объявления переменных, хранящих номера строк.

LONGLONGSIZE

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

LONGSIZE

Эта переменная содержит значение sizeof(long), чтобы препроцессор C мог принимать решения на основе этого значения.

memzero

Устанавливает l байтов, начиная с адреса *d, в нули.

void  memzero(void * d, Size_t l)

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_SHORT_MAX

PERL_SHORT_MIN

PERL_UCHAR_MAX

PERL_UCHAR_MIN

PERL_UINT_MAX

PERL_UINT_MIN

PERL_ULONG_MAX

PERL_ULONG_MIN

PERL_USHORT_MAX

PERL_USHORT_MIN

PERL_QUAD_MAX

PERL_QUAD_MIN

PERL_UQUAD_MAX

PERL_UQUAD_MIN

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

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

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

SHORTSIZE

Эта переменная содержит значение sizeof(short), чтобы препроцессор C мог принимать решения на основе этого значения.

U8

U16

U32

U64

UV

Описание в perlguts.

U32SIZE

Эта переменная содержит sizeof(U32).

U32TYPE

Эта переменная определяет тип C, используемый для Perl's U32.

U64SIZE

Эта переменная содержит sizeof(U64).

U64TYPE

Эта переменная определяет тип C, используемый для Perl's U64.

U16SIZE

Эта переменная содержит sizeof(U16).

U16TYPE

Эта переменная определяет тип C, используемый для Perl's U16.

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)

U8SIZE

Эта переменная содержит sizeof(U8).

U8TYPE

Эта переменная определяет тип C, используемый для Perl's U8.

UV_MAX

Наибольшее беззнаковое целое число, которое помещается в UV на этой платформе.

UV  UV_MAX

UV_MIN

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

UV  UV_MIN

UVSIZE

Эта переменная содержит sizeof(UV).

UVTYPE

Эта переменная определяет тип C, используемый для Perl's UV.

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 или что-то другое.

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)

UTF8f

Описание в perlguts.

UTF8fARG

Описание в perlguts.

UTF8fARG(bool is_utf8, Size_t byte_len, char *str)

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 для символов Юникода. В противном случае они должны интерпретироваться как символы Latin-1. Это аналогично флагу SvUTF8 для скаляров.

В режиме UTF-8 не гарантируется, что буфер лексического анализатора содержит действительный UTF-8. Код лексического анализа должен быть устойчив к некорректной кодировке.

Флаг SvUTF8 скаляра "PL_parser->linestr" важен, но не является единственным фактором кодировки ввода. Обычно, когда файл считывается, скаляр содержит байты, и его флаг SvUTF8 выключен, но байты должны интерпретироваться как UTF-8, если pragma use utf8 активен. Однако во время выполнения строки eval скаляр может иметь флаг SvUTF8 включенным, и в этом случае его байты должны интерпретироваться как UTF-8, если pragma 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, если не null, предоставляет строку (в форме SV) содержащую код для парсинга. Создаётся копия строки, поэтому последующее изменение line не повлияет на парсинг. rsfp, если не null, предоставляет входной поток, из которого будет считываться код для парсинга. Если оба не null, код в 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)