'\" t .\" Hey Emacs! This file is -*- nroff -*- source. .\" .\" This manpage is Copyright (C) 1992 Drew Eckhardt; .\" 1993 Michael Haardt, Ian Jackson; .\" 1998 Jamie Lokier; .\" 2002 Michael Kerrisk. .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" .\" Modified Sat Jul 24 13:39:26 1993 by Rik Faith .\" Modified Tue Sep 26 21:47:21 1995 by Andries Brouwer .\" and again on 960413 and 980804 and 981223. .\" Modified Fri Dec 11 17:57:27 1998 by Jamie Lokier .\" Applied correction by Christian Ehrhardt - aeb, 990712 .\" Modified 23 Apr 02, Michael Kerrisk, .\" Added note on F_SETFL and O_DIRECT .\" Complete rewrite + expansion of material on file locking .\" Incorporated description of F_NOTIFY, drawing on .\" Stephen Rothwell's notes in Documentation/dnotify.txt. .\" Added description of F_SETLEASE and F_GETLEASE .\" Corrected and polished, aeb, 020527. .\" .\" Дата последней коррекции перевода 07.01.2005 .\" Перевод с английского сделал Виктор Вислобоков .\" http://www.linuxshare.ru/projects/trans/mans.html .\" .TH FCNTL 2 2002-04-24 Linux-2.5.18 "Руководство программиста Linux" .SH ИМЯ fcntl \- манипуляции с файловым дескриптором .SH ОБЗОР .nf .B #include .B #include .sp .BI "int fcntl(int " fd ", int " cmd ); .BI "int fcntl(int " fd ", int " cmd ", long " arg ); .BI "int fcntl(int " fd ", int " cmd ", struct flock *" lock ); .fi .SH ОПИСАНИЕ .B fcntl выполняет одну из различных дополнительных операций над файловым дескриптором .IR fd . Эта операция определяется содержимым аргумента .IR cmd . .SS "Управление close-on-exec" .TP .B F_DUPFD Ищет наименьший доступный номер файлового дескриптора, который больше .I arg и делает его копией дескриптора .IR fd . Фактически это другая форма вызова .BR dup2 (2) которая используется с явным указанием файлового дескриптора. .sp Старый и новый дескрипторы могут использоваться равнозначно. Они разделяют одни и те же блокировки, указатели на позиции в файле и флаги; например, если позция в файле изменяется с помощью .B lseek для одного из дескрипторов, то эта же позиция также будет изменена и для другого. .sp Однако, данные два дескриптора не разделяют флаг close-on-exec. Флаг close-on-exec в копии выключен. Это означает, что дескриптор не будет закрыт в случае вызова exec. .sp При успешном выполнении этой операции, возвращается новый файловый дескриптор. .TP .B F_GETFD Читает флаг close-on-exec. Если бит .B FD_CLOEXEC установлен в 0, то файл будет оставлен открытым при вызове .BR exec , в противном случае он будет закрыт. .TP .B F_SETFD Устанавливает флаг close-on-exec в значение, заданное битом .B FD_CLOEXEC аргумента .IR arg . .SS "Флаги состояния файла" Любой файловый дескриптор имеет несколько связанных с ним флагов, которые инициализируются вызовом .BR open (2) .\" or .\" .BR creat (2), и, возможно, изменяются затем вызовом .BR fcntl (2). Эти флаги разделяются между копиями (сделанными с помощью .BR dup (2), .BR fork (2), и других вызовов) этого же файлового дескриптора. .sp Эти флаги и их смысл описываются на странице руководства .BR open (2). .TP .B F_GETFL Читает флаги файлового дескриптора. .TP .B F_SETFL Устанавливает часть флагов, относящихся к состоянию файла, согласно значению, указанному в аргументе .IR arg . Оставшиеся биты (режим доступа, флаги создания файла) в значении .I arg игнорируются. В Linux данная команда может изменять только флаги O_APPEND, O_NONBLOCK, O_ASYNC и O_DIRECT. .P .SS "Совместная (advisory) блокировка" .BR F_GETLK ", " F_SETLK " и " F_SETLKW используются для установки, снятия и тестирования существующих блокировок записи (также известных как блокировки сегмента файла или области файла). Третий аргумент .I lock является указателем на структуру, которая имеет по крайней мере следующие поля (в произвольном порядке). .in +2n .nf .sp struct flock { ... short l_type; /* Тип блокировки: F_RDLCK, F_WRLCK, F_UNLCK */ short l_whence; /* Как интерпретировать l_start: SEEK_SET, SEEK_CUR, SEEK_END */ off_t l_start; /* Начальное смещение для блокировки */ off_t l_len; /* Количество байт для блокировки */ pid_t l_pid; /* PID процесса блокирующего нашу блокировку (F_GETLK only) */ ... }; .fi .in -2n .P Поля .IR l_whence ", " l_start " и " l_len этой структуры задают диапазон байт, который мы хотим заблокировать. .I l_start \- это начальное смещение для блокировки, которое интерпретируется как: начало файла (если значение .I l_whence установлено в .BR SEEK_SET ); текущая позиция в файле (если значение .I l_whence установлено в .BR SEEK_CUR ); или конец файла (если значение .I l_whence установлено в .BR SEEK_END ). В последних двух случаях, .I l_start может иметь отрицательное значение, предоставляя смещение, которого не может быть перед началом файла. .I l_len \-это неотрицательное целое число (но см. ЗАМЕЧАНИЯ ниже), которое задаёт количество байт, которые будут заблокированы. Байты следующие после конца файла могут быть заблокированы, но это нельзя сделать для байтов, которые находятся перед началом файла. Значение 0 для .I l_len имеет специальное назначение: блокировка всех байтов, начиная от позиции, заданной .IR l_whence " и " l_start до конца файла, не зависимо от того, насколько велик файл. .P Поле .I l_type может быть использовано для указания типа блокировки: чтение .RB ( F_RDLCK ) или запись .RB ( F_WDLCK ). Блокировку на чтение (разделяемая блокировка) на область файла может удерживать любое количество процессов, но только один процесс может удерживать блокировку на запись (эксклюзивная блокировка). Любая эксклюзивная блокировка исключает все другие блокировки, как разделяемые так и эксклюзивные. Один процесс может удерживать только один тип блокировки области файла; если происходит новая блокировка на уже заблокированную область, то существующая блокировка преобразуется в новый тип блокировки. (Такие преобразования могут привести к разбиению, уменьшению или срастанию с существующей блокировкой, если диапазон байт, заданный для новой блокировки неточно совпадает с диапазоном существующей блокировки.) .TP .B F_SETLK Установить блокировку (когда .I l_type установлено в значение .B F_RDLCK или .BR F_WRLCK ) или снять блокировку (когда .I l_type установлено в значение .BR F_UNLCK ) или байты, заданны с помощью полей .IR l_whence ", " l_start " и " l_len структуры .IR lock . Если конфликтующая блокировка удерживается другим процессом, то данный вызов вернёт \-1 и установит значение .I errno в .B EACCES или .BR EAGAIN . .TP .B F_SETLKW Если устнаовлен .BR F_SETLK , но для файла удерживается конфликтующая блокировка, то происходит ожидание снятия блокировки. Если во время ожидания поступил сигнал, то данный вызов прерывается и (после возврата из обработчика сигнала) из него происходит немедленный возрат (где возвращаемое значение установлено в \-1, а .I errno установлено в значение .BR EINTR ). .TP .B F_GETLK При входе в этот вызов, .I lock описывает блокировку, которую мы должны бы установить на файл. Если такая блокировка не может быть установлена, .BR fcntl () по факту не устанавливает её, но возвращает .B F_UNLCK в поле .I l_type структуры .I lock и оставляет другие поля структуры неизменёнными. Если одна или более несовместимых блокировок мешают установке нашей блокировки, то .BR fcntl () возвращает подробности об одной из этих блокировок в полях .IR l_type ", " l_whence ", " l_start " и " l_len структуры .I lock и устанавливает .I l_pid в значение PID того процесса, который удерживает блокировку. .P Для того, чтобы установить блокировку на чтение, .I fd должен быть открыт на чтение. Для того, чтобы установить блокировку на запись, .I fd должен быть открыт на запись. Чтобы установить оба типа блокировки, дескриптор должен быть открыт на запись и на чтение. .P Также, как и при снятии блокировки через явное указание .BR F_UNLCK , блокировка автоматически снимается, когда процесс завершается или если он закрывает .I любой файловый дескриптор, ссылающийся на файл, на котором удерживается блокировка. .\" (Additional file descriptors referring to the same file .\" may have been obtained by calls to .\" .BR open "(2), " dup "(2), " dup2 "(2), or " fcntl (2).) Это плохо: это означает, что процесс может потерять блокировки на файлах типа .I /etc/passwd или .IR /etc/mtab , когда по какой-либо причине библиотечная функция производит их открытие, чтение и закрытие. .P Блокировки не наследуются процессом-потомком, созданным через .BR fork (2), но сохраняются при вызове .BR execve (2). .P Поскольку буферизация, выполняется через библиотеку .BR stdio (3), использование блокировок с функциями в этом пакете нужно избегать; вместо этих функций используйте .BR read "(2) и " write (2). .P .SS "Обязательная (mandatory) блокировка" (Не-POSIX.) Описанные выше блокировки могут быть или совместные или обязательные и по умолчанию используются совместные. Чтобы использовать обязательные блокировки, они должны быть разрешены (с помощью опции "-o mand" в .BR mount (8)) для файловой системы, содержащей файл, который должен быть заблокирован, а также разрешены для самого файла (с помощью запрещения прав на выполнение группой и установки set-GID бита в правах доступа к файлу). Совместные блокировки не являются принудительными и полезны только между сотрудничающими процессами. Обязательные блокировки являются принудительными для всех процессов. .P .SS "Управление сигналами" .BR F_GETOWN ", " F_SETOWN ", " F_GETSIG " и " F_SETSIG используются для управления сигналами доступности ввода/вывода: .TP .B F_GETOWN Получить идентификатор процесса или группу процесса, которые в текущий момент принимают сигналы SIGIO и SIGURG для событий на файловом дескрипторе .IR fd . Группы процессов возвращаются в виде отрицательных значений. .TP .B F_SETOWN Установить идентификатор процесса или группу процесса, которые будут принимать сигналы SIGIO и SIGURG для событий на файловом дескрипторе .IR fd . Группы процессов задаются в виде отрицательных значений. .RB ( F_SETSIG может использоваться, чтобы задать другой сигнал вместо SIGIO). .\" From glibc.info: Если вы установили на файловый дескриптор флаг состояния .B O_ASYNC (или через предоставление этого флага в вызове .IR open (2), или используя команду .B F_SETFL вызова .BR fcntl ), то сигнал SIGIO посылается всякий раз, когда для данного файлового дескриптора становится возможным ввод или вывод. .sp Процесс или группа процесса, для приёма сигнала могут быть выбраны, используя команду .B F_SETOWN в вызове .BR fcntl . Если файловым дескриптором является сокет, то для него также выбирается получатель сигналов SIGURG, которые доставляются, когда на сокет поступает данных больше, чем его пропускная способность. (SIGURG посылается во всех ситуациях, когда вызов .BR select (2) говорит, что сокет находится в состоянии "исключительной ситуации"). Если файловый дескриптор соответствует терминальному устройству, то группе процессов, которые работают с терминалом не в фоновом режиме будут посылаться сигналы SIGIO. .TP .B F_GETSIG Получить сигнал, который будет послан, когда станет возможен ввод или вывод. Значение 0 означает сигнал SIGIO. Любое другое значение (включая SIGIO) является другим сигналам, посылаемым вместо SIGIO и в это случае, для обработчика сигнала доступна дополнительная информация, если он был установлен с SA_SIGINFO. .TP .B F_SETSIG Установить сигнал, который будет послан, когда станет возможен ввод или вывол. Значение 0 означает сигнал SIGIO. Любое другое значение (включая SIGIO) является другим сигналам, посылаемым вместо SIGIO и в это случае, для обработчика сигнала доступна дополнительная информация, если он был установлен с SA_SIGINFO. .sp В случае использования F_SETSIG с ненулевым значением и установкой SA_SIGINFO для обработчика сигнала (см. .BR sigaction (2)), обработчику передаётся дополнительная информация о событиях ввода/вывода в структуре .IR siginfo_t . Если поле .I si_code показывает, что сигналом является SI_SIGIO, то поле .I si_fd содержит файловый дескриптор, ассоциированный с собрытием вывода/вывода. В противном случае, не существует никакого механизма, чтобы сообщить с каким файловым дескриптором связан полученный сигнал и вы должны использовать .RB ( select (2), .BR poll (2), .BR read (2) с установленным флагом .B O_NONBLOCK и т.д.) чтобы определить какой файловый дескриптор доступен для ввода/вывода. .sp При выборе сигнала реального времени (value >= SIGRTMIN) как описано в POSIX.1b, в очередь будут добавляться несколько событий ввода вывода, с теми же номерами сигналов. (Размер очереди зависит от доступной памяти). Дополнительная информация будет доступна как описано выше, если для обработчика сигнала будет установлено SA_SIGINFO. .PP Используя эти механизмы, программа может реализовать полностью асинхронный ввода/вывод без использования в своей работе .BR select (2) или .BR poll (2). .PP Использование .BR O_ASYNC , .BR F_GETOWN , .B F_SETOWN является специфичным для BSD и Linux. .B F_GETSIG и .B F_SETSIG являются специфичными для Linux. POSIX описывает асинхронный ввод/вывод и структуру .I aio_sigevent используемую для сходных вещей; которые также доступны в Linux как часть библиотеки GNU C (Glibc). .P .SS "Аренда" .B F_SETLEASE и .B F_GETLEASE (в Linux 2.4 и выше) используются (соответственно) для установки и получения текущих настроек вызывающего процесса, арендующего файл, на который указывает .IR fd . Аренда файла предоставляет такой механизм, когда процесс, удерживающий аренду ("держатель аренды") уведомляется (через доставку сигнала), о том, что другой процесс ("конкурент") пытается выполнить .BR open (2) или .BR truncate (2) для этого файла. .TP .B F_SETLEASE Устанавливает или удаляет аренду файла, в соответствии со целым значением, установленным в аргументе .IR arg : .RS .TP .B F_RDLCK Установить аренду чтения. Это приведёт к генерации уведомления, когда другой процесс открывает указанный файл для записи или усекает его. .TP .B F_WRLCK Установить аренду записи. Это приведёт к генерации уведомления, когда другой процесс открывает указанный файл (для чтения или записи) или усекает его. Аренда записи может быть установлена на файл, только если этот файл не открыт в этот момент каким-либо другим процессом. .TP .B F_UNLCK Удалить аренду с указанного файла. .RE .P Процесс может удержитвать для файла только один тип аренды. .P Аренда может быть установлена только для обычных файлов. Непривелегированный процесс может установить аренту только для файла, у которого UID совпадает с UID файловой системы этого процесса. .TP .B F_GETLEASE Показывает какой тип аренды удерживается для файла, на который указывает .I fd и возвращает одно из значений .BR F_RDLCK ", " F_WRLCK " или " F_UNLCK, соответственно показывающих, что вызывающий процесс удерживает аренду чтения, записи или что аренды нет. (Третий аргумент .BR fcntl () при этому опускается.) .PP Когда конкурент выполняет вызов .BR open () или .BR truncate (), который конфликтует с арендой, установленной через .BR F_SETLEASE , системный вызов блокируется ядром (за исключением случая, когда при вызове .BR open () указывается флаг .BR O_NONBLOCK ; в этом случае немедленно возращается ошибка .BR EWOULDBLOCK ). Затем ядро уведомляет держателя аренды, отправляя ему сигнал (по умолчанию SIGIO). Держатель аренты должен при получении этого сигнала выполнить все необходимые действия для подготовки этого файла к использованию другим процессом (например, сбросить буферы кэша) и затем удалить аренду, выполнив операцию .B F_SETLEASE и установив значение аргумента .I arg в .BR F_UNLCK . Если держатель аренды не освободит аренду в течении количества секунд, которое задаётся в файле .IR /proc/sys/fs/lease-break-time , а системный вызов конкурента останется блокирующим (то, есть конкурент не установит флаг .B O_NONBLOCK для системного вызова .BR open () и этот системный вызов не будет прерван обработчиком события), то ядро принудительно удалит аренду у процесса держателя аренды. После того как аренда снята держателем аренды или принудительно удалена ядром, ядро снимает блокировку с системного вызова процесса конкуренту и разрешает продолжить его работу. По умолчанию, для уведомления держателя аренды используется сигнал SIGIO, но его можно изменить, используя команду .B F_SETSIG для .B fcntl (). Если выполняется команда .B F_SETSIG (даже назначая сигнал SIGIO) и при этом обработчик сигнала устанавливается с использованием SA_SIGINFO, то обработчик будет получит в качестве второго аргумента структуру .IR siginfo_t , в которой поле .I si_fd будет содержать дескриптор файла, для которого установлена аренда и которому пытается получить доступ другой процесс. (Это полезно, если вызывающий процесс удерживает аренду на несколько файлов). .SS "Уведомления об изменении файла и каталога" .TP .B F_NOTIFY (Начиная с Linux 2.4) Предоставляет уведомление, когда изменяется каталог, на который указывает .I fd или файлы, которые в нём содержатся. События, о наступлении которых делается уведомление, задаются в аргументе .IR arg , который является битовой маской, получаемой битовым сложением (OR) одной или более следующих масок: .TS l l ---- lB l. Маска Описание (событие в каталоге) DN_ACCESS Был осуществлён доступ к файлу (read, pread, readv) DN_MODIFY Файл был изменён (write, pwrite, writev, truncate, ftruncate) DN_CREATE Файл был создан (open, creat, mknod, mkdir, link, symlink, rename) DN_DELETE Файл был удалён (unlink, rename в другой каталог, rmdir) DN_RENAME Файл был переименован внутри каталога (rename) DN_ATTRIB У файла был изменён атрибут (chown, chmod, utime[s]) .TE .sp (Чтобы включить определения этих масок, нужно задать макроопределение _GNU_SOURCE до подключения .) .sp Уведомления об изменении состояния каталога обычно однократные и приложение должно перерегистрировать установку уведомлений, чтобы и дальше получать их. Однако, если в аргумент .IR arg добавить маску .BR DN_MULTISHOT , то уведомления будут происходить до тех пор, пока не будут явно отменены. .\" The following does seem a poor API-design choice... Серии запросов .B F_NOTIFY накапливаются, таким образом запросы на уведомления, указываемые в .I arg будут добавляться к тем, что уже установлены. Чтобы запретить уведомления для всех событий, выполните вызов .BR F_NOTIFY , в котором значение .I arg установлено в 0. .sp Уведомления выполняются через доставку сигнала. По умолчанию - это SIGIO, но вы можете изменить его, используя команду .B F_SETSIG для вызова .BR fcntl (). В последнем случае, обработчик сигнала получит в качестве второго аргумента структуру .I siginfo_t (если обработчик был установлен с использованием SA_SIGINFO), а поле .I si_fd в этой структуре будет содержать дескриптор файла, для которого было сегенерировано уведомление (полезно, когда устанавливается уведомление для нескольких каталогов). .sp Кроме того, когда используется .BR DN_MULTISHOT , для уведомлений должен бы быть использован сигнал реального времени POSIX.1b, так что множественные уведомления могут быть поставлены в очередь. .SH "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ" При успешном вызове, возвращаемое значение зависит от использованной операции: .TP 0.9i .B F_DUPFD Новый файловый дескриптор. .TP .B F_GETFD Значение флага. .TP .B F_GETFL Значение флага. .TP .B F_GETOWN Значение, представляющее собой владельца дескриптора. .TP .B F_GETSIG Значение сигнала, посылаемого когда становится возможным чтение или запись или ноль для традиционного поведения SIGIO. .TP Все другие команды. Ноль. .PP В случае ошибки, возвращается \-1 и значение .I errno устанавливается соответствующим образом. .SH ОШИБКИ .TP .BR EACCES " или " EAGAIN Операция запрещена блокировками, которые удерживаются другими процессами. Или, операция запрещена, потому что для этого файла другой процесс использует механизм отображения в память (memory-map). .TP .B EBADF .I fd не является открытым файловым дескриптором или команда была .B F_SETLK или .B F_SETLKW и режим открытия файлового дескриптора не совпадает с типом запрошенной блокировки. .TP .B EDEADLK Было обнаружено, что указанная команда .B F_SETLKW должна вызывать мёртвую блокировку (deadlock). .TP .B EFAULT .I lock находится за пределами доступного адресного пространства. .TP .B EINTR Выполнение команды .BR F_SETLKW , было прервана сигналом. Или выполнение команд .BR F_GETLK " и " F_SETLK , было прервано сигналом перед тем как была блокировка была проверка или установлена. Большинство таких ошибок случается при блокировке удалённого файла (например, блокировка через NFS), но иногда такое может случаться и на локальных файлах. .TP .B EINVAL Для .BR F_DUPFD , значение .I arg отрицательное или же больше, чем максимально возможное значение. Для .BR F_SETSIG , значение .I arg не содержит допустимый номер сигнала. .TP .B EMFILE Для .BR F_DUPFD , процесс достиг максимального количества открытых файловых дескрипторов. .TP .B ENOLCK Открыто слишком много блокировок сегментов, таблица блокировок заполнена или ошибка протокола удалённой блокировки (например, при блокировке через NFS). .TP .B EPERM Попытка сбросить флаг .B O_APPEND на файле, который открыт с атрибутом только для добавления. .SH ЗАМЕЧАНИЯ Ошибки, возвращаемые .B dup2 отличаются от тех, что возвращаются при .BR F_DUPFD . Начиная с ядра 2.0, не существует разницы между типами блокировки, которые осуществляет .BR flock (2) и .BR fcntl (2). POSIX 1003.1-2001 разрешает отрицательное значение .IR l_len . (И если оно отрицательное, интервал, описывающий блокировку покрывает .IR l_start + l_len байт, включая .IR l_start -1.) Это поддерживатся, начиная с Linux 2.4.21 и 2.5.49. Некоторые системы имеют больше полей в структуре .I "struct flock" например такие как .IR l_sysid . Вообще-то, один .I l_pid не очень-то полезен, если процесс, удерживающий блокировку может работать на другой машине. .SH "СООТВЕТСТВИЕ СТАНДАРТАМ" SVr4, SVID, POSIX, X/OPEN, BSD 4.3. В стандарте POSIX.1 описываются только F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK и F_SETLKW. F_GETOWN и F_SETOWN в BSD, не поддеживаются в SVr4; F_GETSIG и F_SETSIG являются специфичными для Linux. .BR F_NOTIFY ", " F_GETLEASE ", и " F_SETLEASE являются специфичными для Linux. (Для подключения этих флагов задавайте макрос _GNU_SOURCE перед подключением заголовочного файла .) Флаги, которые являются допустимыми для F_GETFL/F_SETFL также поддерживаются вызовом .BR open (2) и варьируются в зависимости от операционных систем; O_APPEND, O_NONBLOCK, O_RDONLY и O_RDWR описываются в POSIX.1. SVr4 поддерживает несколько других опций и флагов, которые здесь не описываются. .PP SVr4 документирует дополнительные условия ошибок EIO, ENOLINK и EOVERFLOW. .SH "СМОТРИ ТАКЖЕ" .BR dup2 (2), .BR flock (2), .BR lockf (3), .BR open (2), .BR socket (2) .P См. также locks.txt, mandatory.txt и dnotify.txt in /usr/src/linux/Documentation. .SH ПЕРЕВОД Перевёл с английского Виктор Вислобоков 2005