perlfunc

=head1 НАЗВАНИЕ
X<function>

perlfunc - встроенные функции Perl

=head1 ОПИСАНИЕ

Функции в этом разделе могут служить в качестве термов в выражениях. Они разделяются на две основных категории: списковые операторы и именованные унарные операторы. Они различаются приоритетом (см. таблицу приоритетов в L<perlop>). Списочные операторы принимают более одного аргумента, тогда как унарные не могут принимать более одного. Таким образом, запятая ограничивает аргумент унарного оператора, разделяя аргументы спискового оператора. Унарный оператор принимает аргумент в скалярном контексте, а списочный может принимать как скалярный, так и списочный. Если используются оба вида вместе, то скалярные аргументы должны быть первыми, а списочный аргумент должен следовать за ними. (Учтите, что здесь может быть только один списочный аргумент.) Для примера, splice() имеет три скалярных аргумента, после чего список, тогда как gethostbyname() имеет четыре скалярных аргумента.

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

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

print 1+2+4; # Печатает 7.
print(1+2) + 4; # Печатает 3.
print (1+2)+4; # Также печатает 3!
print +(1+2)+4; # Печатает 7.
print ((1+2)+4); # Печатает 7.

Если вы запускаете Perl с ключом B<-w>, он предупредит вас об этом. Например, для третьей строки в приведенном примере будет выведено:

print (...) interpreted as function at - line 1.
Useless use of integer addition in void context at - line 1.

Некоторые функции не принимают аргументы вовсе и работают не так, как унарные и списочные. В их число входят такие функции, как C<time> и C<endpwent>. Например, C<time+86_400> всегда означает C<time() + 86_400>.

Для функций, которые могут быть использованы и в списочном, и в скалярном контексте, не фатальная ошибка обозначается в скалярном контексте возвратом неопределенного значения, а в списочном контексте - пустым списком.

Запомните важное правило: B<Нет правила>, которое связывает поведение выражения в списочном контексте с его поведением в контексте скалярном, или наоборот. Это могут быть две совершенно разные вещи. Каждый оператор и функция решает, какой вид значений может быть наиболее приемлем для возвращения в скалярном контексте. Некоторые операторы возвращают длину списка который мог бы быть возвращен в списочном контексте. Некоторые операторы возвращают первое значение списка. Некоторые возвращают последнее значение списка. Некоторые операторы возвращают число удачных операций. Резюмируя, они делают что вы хотите, если вы последовательны в действии. X<context>

Именованный массив в скалярном контексте на самом деле отличается от того, чем на первый взгляд кажется список в скалярном контексте. Вы не можете получить список вроде C<(1,2,3)> в скалярном контексте, т.к. компилятор "знает" контекст на стадии компиляции. Он сгенерирует скалярный оператор "," (запятая), а не его версию, используемую для построения списков. Это значит, что …

В общем, функции Perl, служащие обёртками для одноимённых системных вызовов (подобно chown(2), fork(2), closedir(2) и т.д.), в случае успешного завершения возвращают истинное значение, а иначе — C<undef>, как об этом обычно упоминается в описаниях ниже. Такое поведение отличается от интерфейсов C, в которых при неудаче возвращается C<-1>. Исключениями из этого правила являются C<wait>, C<waitpid> и C<syscall>. Также при неудаче системные вызовы устанавливают специальную переменную C<$!>. Остальные функции этого не делают, разве что случайно.

=head2 Список функций Perl по категориям
X<function>

Здесь представлены функции Perl (включая то, что выглядит как функции, наподобие ключевых слов и именованных операторов), сгруппированные по категориям. Некоторые функции встречаются более чем в одной категории.

=over 4

=item Функции для работы со СКАЛЯРАМИ или строками
X<scalar> X<string> X<character>

C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>, C<length>, C<oct>, C<ord>, C<pack>, C<q//>, C<qq//>, C<reverse>, C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>

=item Регулярные выражения и поиск по шаблону
X<regular expression> X<regex> X<regexp>

C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//>

=item Числовые функции
X<numeric> X<number> X<trigonometric> X<trigonometry>

C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>, C<sin>, C<sqrt>, C<srand>

=item Функции для работы с именованными @МАССИВАМИ
X<array>

C<pop>, C<push>, C<shift>, C<splice>, C<unshift>

=item Функции для работы со списками

C<grep>, C<join>, C<map>, C<qw//>, C<reverse>, C<sort>, C<unpack>

=item Функции для работы с именованными %ХЭШАМИ
X<hash>

C<delete>, C<each>, C<exists>, C<keys>, C<values>

=item Функции ввода/вывода
X<I/O> X<input> X<output> X<dbm>

C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
C<readdir>, C<rewinddir>, C<say>, C<seek>, C<seekdir>, C<select>, C<syscall>,
C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
C<warn>, C<write>

=item Функции для работы с данными/записями фиксированной длины

C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>

=item Функции для работы с файловыми дескрипторами, файлам, директориями
X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink>

C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
C<umask>, C<unlink>, C<utime>

=item Ключевые слова для контроля потока управления ваших Perl программ
X<control flow>

C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>, C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>

=item Ключевые слова для управления выполнением циклов

C<break>, C<continue>, C<given>, C<when>, C<default>

(Доступны только если вы включите опцию "switch".
Смотрите L<feature> и L<perlsyn/"Switch-выражения">.)

=item Ключевые слова для управлению областью видимости

C<caller>, C<import>, C<local>, C<my>, C<our>, C<state>, C<package>, C<use>

(C<state> доступна только при включенной опции "state". Смотрите L<feature>.)

=item Другие различные функции

C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>, C<scalar>, C<state>, C<undef>, C<wantarray>

=item Функции для работы с процессами и процессными группами
X<process> X<pid> X<process id>

C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>, C<pipe>, C<qx//>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>, C<times>, C<wait>, C<waitpid>

=item Ключевые слова относящиеся к модулям Perl

C<do>, C<import>, C<no>, C<package>, C<require>, C<use>

=item Ключевые слова относящиеся к классам и ОО
X<object> X<class> X<package>

C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
C<untie>, C<use>

=item Низкоуровневые функции для работы с сокетами

C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>, C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>, C<socket>, C<socketpair>

=item Функции для межпроцессного взаимодействия в System V стиле
X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message>

C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>, C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>

=item Получение информации о пользователе и его группе
X<user> X<group> X<password> X<uid> X<gid> X<passwd> X</etc/passwd>

C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>, C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>, C<getpwuid>, C<setgrent>, C<setpwent>

=item Получение сетевой информации
X<network> X<protocol> X<host> X<hostname> X<IP> X<address> X<service>

C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>, C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>, C<getprotobyname>, C<getprotobynumber>, C<getprotoent>, C<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>, C<setnetent>, C<setprotoent>, C<setservent>

=item Функции для работы с временем
X<time> X<date>

C<gmtime>, C<localtime>, C<time>, C<times>

=item Новые функции в perl5
X<perl5>

C<abs>, C<bless>, C<break>, C<chomp>, C<chr>, C<continue>, C<default>, C<exists>, C<formline>, C<given>, C<glob>, C<import>, C<lc>, C<lcfirst>, C<lock>, C<map>, C<my>, C<no>, C<our>, C<prototype>, C<qr//>, C<qw//>, C<qx//>, C<readline>, C<readpipe>, C<ref>, C<sub>*, C<sysopen>, C<tie>, C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use>, C<when>

* - C<sub> было ключевым словом в perl4, но в perl5 это оператор, который может использоваться в выражениях.

=item Устаревшие в perl5 функции

C<dbmclose>, C<dbmopen>

=back

=head2 Портируемость
X<portability> X<Unix> X<portable>

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

C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>, C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>, C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>, C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostbyname>, C<gethostent>, C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>, C<getppid>, C<getpgrp>, C<getpriority>, C<getprotobynumber>, C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>, C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>, C<kill>, C<link>, C<lstat>, C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>, C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>, C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>, C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>, C<socket>, C<socketpair>, C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>, C<times>, C<truncate>, C<umask>, C<unlink>, C<utime>, C<wait>, C<waitpid>

Для более подробной информации по портируемости этих функций см. L<perlport> и доступную платформенно-зависимую документацию.

=head2 Алфавитный указатель функций Perl

=over 8

=item -X FILEHANDLE
X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>

=item -X EXPR

=item -X DIRHANDLE

=item -X

Проверка файла, где X - один из перечисленных далее символов. Унарный оператор принимает один аргумент, это может быть имя файла, файловый дескриптор, либо дескриптор каталога, и проверяет соответствующий файл на соответствие условию. Ели аргумент не указан, проверяет C<$_>, кроме работы с ключом C<-t>, при котором проверяется STDIN. Если не оговорено иное, возвращает C<1> для успешной проверки и C<''> для провалившейся, либо неопределенное значение если файл не существует. Несмотря на забавные имена, приоритет у файловых проверок такой же как и у прочих именованных унарных операторов. Оператор может быть один из:

-r Файл можно читать под текущим effective uid/gid
-w В файл можно писать под текущим effective uid/gid.
-x Файл можно выполнить под текущим effective uid/gid.
-o Владельцем файла является пользователь с текущим effective uid.

-R Файл можно читать под текущим real uid/gid.
-W В файл можно писать под текущим real uid/gid.
-X Файл можно выполнить под текущим real uid/gid.
-O Владельцем файла является пользователь с текущим real uid.

-e Файл существует.
-z Файл нулевой длины (пустой).
-s Файл ненулевой длины (возвращает размер в байтах).

-f Файл является простым файлом.
-d Файл является директорией.
-l Файл является символической ссылкой.
-p Файл является именованным каналом (FIFO) или файловый дескриптор является конвейером.
-S Файл является сокетом.
-b Файл блочного режима.
-c Файл символьного режима.
-t Файловый дескриптор открыт на tty.

-u У файла установлен setuid-бит.
-g У файла установлен setgid-бит.
-k У файла установлен sticky-бит.

-T Файл содержит ASCII текст (эвристическая догадка).
-B Файл является бинарным (противоположность -T).

-M Время запуска скрипта минус время последней модификации файла, в днях.
-A Тоже самое, только с временем последнего доступа.
-C Тоже самое, только с временем модификации inode (может различаться на отличных от Unix платформах)

Пример:

while (<>) {
chomp;
next unless -f $_; # пропускаем специальные файлы
#...
}

Реализация операторов проверки прав (C<-r>, C<-R>, C<-w>, C<-W>, C<-x> и C<-X>) целиком основана на битах прав файла, пользовательских и групповых идентификаторах. Есть и другие причины, из-за которых вы не сможете прочесть/записать/выполнить файл. Например: контроль доступа в сетевых ФС, ACL, файловые системы только для чтения, нераспознанный формат исполняемого файла. Заметьте, что использование шести вышеупомянутых операторов для решения о возможности какой-то из операций обычно является ошибкой, т.к. они [операторы] могут вызвать состояние гонки.

Также заметьте, что для супер-пользователя на локальной ФС проверки C<-r>, C<-R>, C<-w>, C<-W> всегда будут возвращать 1, а C<-x> и C<-X> будет возвращать 1 при любом выставленном бите исполнения. Из-за этого скрипты запущенные супер-пользователем должны вызывать stat() для определения актуальных прав, или, как вариант, временно изменять свой effective uid.

Если вы используете ACL, то вам поможет директива C<filetest>, которая производит более точную проверку по сравнению с stat(). При включенной директиве C<use filetest 'access'> вышеупомянутые операторы будут работать, используя семейство системных вызовов access(). Имейте в виду, что с включенной директивой операторы C<-x> и C<-X> могут возвращать истинное значение, даже если биты права на выполнение не выставленны (и не выставлены какие-то особые права в ACL). Эта странность происходит из-за реализации низкоуровневых системных вызовов.
При активации поддирективы 'access', из-за ее реализации, специальный файловый дескриптор C<_> не будет кэшировать результаты выполнения проверочных операторов. Для более подробной информации обратитесь к документации директивы C<filetest>.

Обратите внимание, что C<-s/a/b/> ... Выражение C<-exp($foo)> работает как и ожидается, а вот одна буква и минус перед ней интепретируется как оператор проверки файла.

Операторы C<-T> и C<-B> работают так: первый блок (примерно) файла проверяется на присутствие нестандартных символов, например необычных служебных кодов или символов с высоким номером ASCII. Если таких символов окажется много (более 30%), то это C<-B>-файл (бинарный), иначе это C<-T>-файл (текстовый). Также любой файл содержащий нулевой байт в первом блоке рассматривается как бинарный. Если аргументом C<-T> или C<-B> является файловый дескриптор, то вместо первого блока проверяется текущий буфер ввода/вывода. Оба оператора возвращают ИСТИНУ для пустых файлов и файловых дескрипторах находящихся в позиции EOF. Т.к. для проверки C<-T> вам надо читать файл, то в большинстве случаев сначала лучше использовать C<-f>. Пример: C<next unless -f $file && -T $file>.

Если любому из проверочных операторов (или вызовам C<stat> или C<lstat>) в качестве аргумента передается специальный файловый дескриптор "_", то используется структура с результатом предущей проверки (или вызова stat). Таким образом экономится системный вызов (это не сработает для C<-t>, а также надо помнить, что C<lstat()> и C<-l> сохранят результат для файла-ссылки, а не конечного файла) (если stat-кэш был заполнен вызовом C<lstat>, то C<-T> и C<-B> перезапишут его результатом вызова C<stat _>).

print "Can do.\n" if -r $a || -w _ || -x _;

stat($filename);
print "Readable\n" if -r _;
print "Writable\n" if -w _;
print "Executable\n" if -x _;
print "Setuid\n" if -u _;
print "Setgid\n" if -g _;
print "Sticky\n" if -k _;
print "Text\n" if -T _;
print "Binary\n" if -B _;

Начиная с версии Perl 5.9.1, вы можете использовать синтаксический сахар в виде вложенности проверящих операторов. Таким образом запись C<-f -w -x $file> является эквивалентной C<-x $file && -w _ && -f _> (если вы используете возвращаемое C<-f $file> значение в качестве аргумента другому проверочному оператору, то это не сработает).

=item abs VALUE
X<abs> X<absolute>

=item abs

Возвращает аргумент по модулю (абсолютное значение). Если VALUE не указано, использует C<$_>.

=item accept NEWSOCKET,GENERICSOCKET
X<accept>