Provided by: manpages-pl-dev_0.7-2_all 
NAZWA
fcntl - manipulacje na deskryptorze pliku
SKŁADNIA
#include <unistd.h>
#include <fcntl.h>
int fcntl(int fd, int cmd);
int fcntl(int fd, int cmd, long arg);
int fcntl(int fd, int cmd, struct flock *lock);
OPIS
Uwaga! To tłumaczenie może być nieaktualne!
fcntl dokonuje jednej z wielu różnych operacji na fd. Wykonywana operacja zdeterminowana
jest przez cmd.
Obsługa zamknięcia przy uruchomieniu (close-on-exec)
F_DUPFD
Znalezienie najniższego dostępnego numeru dla deskryptora pliku, wiekszego lub
równego arg i uczynienie deskryptora o tym numerze kopią fd. Jest to inna postać
dup2(2), korzystająca z konkretnego, zadanego deskryptora.
Stare i nowe deskryptory mogą być używane zamiennie. Dzielą one blokady, wskaźniki
pozycji pliku i flagi; na przykład, jeśli pozycja pliku zostanie zmodyfikowana
poprzez użycie lseek na jednym z deskryptorów, zmieni się również pozycja dla
drugiego deskryptora.
Te dwa deskryptory nie współdzielą jednak znacznika "zamknięcia przy uruchomieniu"
(close-on-exec). Znacznik ten dla kopii jest wyzerowany, co oznacza, że kopia nie
zostanie zamknięta podczas wywołania exec.
Po pomyślnym zakończeniu zwracany jest nowy deskryptor.
F_GETFD
Odczytanie znacznika "zamknięcia przy uruchomieniu" (close-on-exec). Jeśli bit
FD_CLOEXEC jest równy 0, to plik pozostanie otwarty po wykonaniu exec, w przeciwnym
przypadku zostanie zamknięty.
F_SETFD
Nadanie znacznikowi "zamknięcia przy uruchomieniu" (close-on-exec) wartości
określonej przez bit FD_CLOEXEC arg.
Znaczniki stanu pliku
Z deskryptorem pliku stowarzyszonych jest kilka znaczników inicjalizowanych przez open(2),
które mogą ewentualnie być modyfokowane przez fcntl(2). Znaczniki są współdzielone przez
kopie (wykonane za pomocą dup(2), fork(2), itp.) tego samego deskryptora pliku.
Znaczniki i ich znaczenie są opisane w open(2).
F_GETFL
Odczytanie znaczników deskryptora.
F_SETFL
Nadanie tym znacznikom deskryptora, które określają stan pliku, wartości określonej
przez arg. Pozostałe bity (prawa dostępu, znaczniki tworzenia pliku) w arg
pozostają niezmienione. Pod Linuksem polecenie to może zmieniać jedynie znaczniki
O_APPEND, O_NONBLOCK, O_ASYNC i O_DIRECT.
Blokowanie doradcze
F_GETLK, F_SETLK i F_SETLKW służą do zakładania, zwalniania i sprawdzania obecności blokad
rekordów (znanych również jako blokady segmentów lub obszarów pliku). Trzeci argument,
lock, jest wskaźnikiem do struktury zawierającej co najmniej następujące pola (kolejność
nie jest określona).
struct flock {
...
short l_type; /* Rodzaj blokady: F_RDLCK,
F_WRLCK, F_UNLCK */
short l_whence; /* Sposób interpretacji l_start:
SEEK_SET, SEEK_CUR, SEEK_END */
off_t l_start; /* Początek (offset) blokady */
off_t l_len; /* Liczba blokowanych bajtów */
pid_t l_pid; /* PID procesu uniemożliwiającego blokadę
(tylko F_GETLK) */
...
};
Pola l_whence, l_start i l_len powyższej struktury określają zakres bajtów, który chcemy
zablokować. l_start jest początkiem (offsetem) blokady i jest interpretowane względem:
początku pliku (gdy l_whence jest równe SEEK_SET); aktualnej pozycji w pliku (gdy l_whence
jest równe SEEK_CUR); lub końca pliku (gdy l_whence jest równe SEEK_END). W dwu ostatnich
przypadkach l_start może być liczbą ujemną o ile pozycja nie znajdzie się przed początkiem
pliku. l_len jest liczbą nieujemną (ale zobacz UWAGI poniżej) określającą liczbę
blokowanych bajtów. Można blokować bajty poza końcem pliku, ale nie przed jego początkiem.
Podanie 0 jako l_len ma specjalne znaczenie: blokowanie wszystkich bajtów począwszy od
pozycji określonej przez l_whence i l_start do końca pliku, niezależnie od tego, jaki duży
stanie się plik.
Pole l_type może służyć do założenia blokady dla odczytu (F_RDLCK) lub dla zapisu
(F_WDLCK) do pliku. Dowolna liczba procesów może utrzymywać blokadę dla odczytu pliku
(blokada wspólna) w pewnym jego obszarze, ale tylko jeden proces może utrzymywać blokadę
dla zapisu do pliku (blokada wyłączna). Blokada wyłączna wyklucza wszelkie inne blokady,
zarówno wspólne, jak i wyłączne. Pojedynczy proces może w danym obszarze pliku utrzymywać
blokadę tylko jednego rodzaju; gdy w aktualnie zablokowanym obszarze zakładana jest nowa
blokada, to istniejąca blokada jest przekształcana w blokadę nowego typu. (Takie
przekształcenie może pociągać za sobą podział, skrócenie lub połączenie z istniejącą
blokadą, gdy zakres bajtów podany dla nowej blokady nie pokrywa się dokładnie z zakresem
istniejącej blokady.)
F_SETLK
Ustawienie blokady dla zakresu bajtów określonego przez pola l_whence, l_start and
l_len lock (gdy l_type jest równe F_RDLCK lub F_WRLCK) albo jej zwolnienie (gdy
l_type jest równe F_UNLCK). Jeśli kolidująca blokada jest utrzymywana przez inny
proces, funkcja ta zwraca -1 i ustawia errno na EACCES lub EAGAIN.
F_SETLKW
Podobne do F_SETLK, lecz w sytuacji, gdy na pliku założona jest kolidująca blokada
czeka na zwolnienie tej blokady. Jeśli podczas oczekiwania zostanie przechwycony
sygnał, funkcja jest przerywana i (po powrocie z funkcji obsługi sygnału) powraca
natychmiast (zwracając wartość -1 i ustawiając errno na EINTR).
F_GETLK
Jako argument lock tej funkcji określa blokadę, jaką chcielibyśmy założyć na pliku.
Gdy założenie blokady jest możliwe, fcntl() w rzeczywistości jej nie zakłada, lecz
zwraca F_UNLCK w polu l_type struktury lock pozostawiając inne pola tej struktury
niezmienione. Jeśli co najmniej jedna niezgodna blokada uniemożliwiłaby założenie
zadanej blokady, to fcntl() zwróci w polach l_type, l_whence, l_start i l_len
struktury lock informacje dotyczące jednej z kolidujących blokad oraz ustawi l_pid
na wartość PID procesu utrzymującego tę blokadę.
Aby założyć blokadę do odczytu, deskryptor fd musi być otwarty do odczytu. Aby założyć
blokadę do zapisu, deskryptor fd musi być otwarty do zapisu. Aby założyć obydwa rodzaje
blokad, należy otworzyć plik do odczytu i zapisu.
Blokady są usuwane w wyniku jawnego F_UNLCK, jak też są one automatycznie zwalniane gdy
proces kończy działanie lub zamyka dowolny deskryptor odnoszący się do pliku, na którym
blokady są utrzymywane. Jest to złe: oznacza, że proces może utracić blokady na pliku
takim jak /etc/passwd lub /etc/mtab gdy jakaś funkcja biblioteczna zdecyduje się z
jakiegoś powodu ten plik otworzyć, odczytać i zamknąć.
Blokady rekordów nie są dziedziczone przez procesy potomne poprzez fork(2), ale są
zachowywane poprzez execve(2).
Ze względu na wykonywane przez bibliotekę stdio(3) buforowanie, należy unikać blokowania
rekordów w połączeniu z funkcjami z tego pakietu; zamiast tego należy używać read(2) i
write(2).
Blokowanie obowiązujące
(Nie POSIX-owe.) Powyższe blokady plików mogą być albo doradcze, albo obowiązujące, a
domyślnie są obowiązujące. Aby skorzystać z obowiązujących blokad, na systemie plików
zawierającym blokowany plik musi być włączone blokowanie obowiązujące (za pomocą opcji "-o
mand" programu mount(8)) oraz musi być ono włączone dla samego pliku (poprzez wyłączenie
prawa uruchamiania dla grupy i włączenie bitu set-GID).
Blokady doradcze nie są wymuszane i są przydatne jedynie pomiędzy współpracującymi
procesami. Blokady obowiązujące są wymuszane dla wszystkich procesów.
Zarządzanie sygnałami
F_GETOWN, F_SETOWN, F_GETSIG i F_SETSIG służą do zarządzania sygnałami dostępności we/wy:
F_GETOWN
Pobranie ID procesu lub grupy procesów aktualnie otrzymujących sygnały SIGIO i
SIGURG dla zdarzeń na deskryptorze plików fd. Grupy procesów są zwracane jako
wartości ujemne.
F_SETOWN
Ustawia ID procesu lub grupy procesów aktualnie otrzymujących sygnały SIGIO i
SIGURG dla zdarzeń na deskryptorze plików fd. Grupy procesów są określane za
pomocą wartości ujemnych. (F_SETSIG może służyć do określenia innego sygnału
zamiast SIGIO).
Jeśli na deskryptorze pliku ustawiony zostanie znacznik stanu O_ASYNC (przez
usttawienie tego znacznika przy wywołaniu open(2), albo przy użyciu polecenia
F_SETFL w fcntl), to gdy wejście lub wyjście dla tego deskryptora pliku stanie się
możliwe, wysłany zostanie sygnał SIGIO.
Proces lub grupę procesów, które otrzymają sygnał można wybrać za pomocą polecenia
F_SETOWN w funkcji fcntl. Jeśli deskryptor pliku jest gniazdem, określa to również
odbiorcę sygnałów SIGURG dostarczanych gdy poprzez gniazdo przybędą dane
autonomiczne. (SIGURG jest wysyłany w sytuacjach, w których select(2) zgłosiłby
"stan wyjątkowy" dla gniazda.) Jeśli deskryptor pliku jest skojarzony z
urządzeniem terminalowym, to sygnały SIGIO są wysyłane do grupy procesów
pierwszoplanowych tego terminala.
F_GETSIG
Pobranie numeru sygnału wysyłanego, gdy wejście lub wyjście stanie się możliwe.
Wartość zerowa oznacza wysyłanie SIGIO. Dowolna inna wartość (łącznie z SIGIO)
stanowi numer sygnału wysyłanego zamiast SIGIO. W tych sytuacjach dodatkowe
informacje mogą być dostępne dla programu obsługi sygnału, o ile zostały
zainstalowane z użyciem SA_SIGINFO.
F_SETSIG
Ustawienie numeru sygnału wysyłanego, gdy wejście lub wyjście stanie się możliwe.
Wartość zerowa oznacza wysyłanie sygnału domyślnego, czyli SIGIO. Dowolna inna
wartość (łącznie z SIGIO) stanowi numer sygnału wysyłanego zamiast SIGIO. W tych
sytuacjach dodatkowe informacje mogą być dostępne dla programu obsługi sygnału, o
ile zostały zainstalowane z użyciem SA_SIGINFO.
Za pomocą F_SETSIG z niezerową wartością i przy ustawionym SA_SIGINFO dla programu
obsługi sygnału (patrz sigaction(2)), można przekazać do programu obsługi sygnału w
strukturze siginfo_t dodatkowe informacje o zdarzeniach we/wy Jeśli pole si_code
wskazuje, że źródłem jest SI_SIGIO, to pole si_fd zawiera deskryptor pliku związany
ze zdarzeniem. W przeciwnym przypadku, brak jest wskazania, które deskryptory
plików oczekują i do określenia dostępnych dla we/wy deskryptorów plików należy
używać zwykłych mechanizmów (select(2), poll(2), read(2) z ustawionym O_NONBLOCK
itd.),
Wybierając sygnał czasu rzeczywistego wg POSIX.1b (wartość >= SIGRTMIN), można,
używając tych samych numerów sygnałów, spowodować umieszczenie w kolejce wielu
zdarzeń we/wy. (Kolejkowanie zależy od dostępnej pamięci.) Jak powyżej, dodatkowe
informacje są dostępne, gdy programy obsługi sygnałów zostały zainstalowane z
ustawionym SA_SIGINFO.
Za pomocą tych mechanizmów program może zaimplementować w pełni asynchroniczne we/wy nie
używając przez większość czasu select(2) i poll(2).
Opisane powyżej korzystanie z O_ASYNC, F_GETOWN, F_SETOWN jest specyficzne dla BSD i
Linuksa. F_GETSIG i F_SETSIG są specyficzne dla Linuksa. POSIX posiada asynchroniczne
we/wy i strukturę aio_sigevent służącą do podobnych celów; w Linuksie są one również
dostępne jako część biblioteki GNU C (glibc).
Dzierżawy
F_SETLEASE i F_GETLEASE (od Linuksa 2.4 wzwyż) służą do (odpowiednio) ustanowienia i
pobrania aktualnego ustawienia dzierżawy na pliku określonym przez fd dla procesu
wywołującego funkcję. Dzierżawa pliku zapewnia mechanizm, w którym proces utrzymujący
dzierżawę ("dzierżawca") jest zawiadamiany (poprzez dostarczenie sygnału) o tym, że inny
proces ("współzawodnik") próbuje wykonać open(2) lub truncate(2) na tym pliku.
F_SETLEASE
Ustawia lub usuwa dzierżawę pliku w zależności od tego, która z następujących
wartości zostanie podana jako argument arg typu integer :
F_RDLCK
Wzięcie dzierżawy odczytu. Spowoduje to zawiadamianie o otwarciu pliku do
zapisu lub jego obcięciu przez inny proces.
F_WRLCK
Wzięcie dzierżawy zapisu. Spowoduje to zawiadamianie o otwarciu pliku (do
odczytu lub do zapisu) lub obcięciu go przez inny proces. Dzierżawa zapisu
może zostać nałożona na plik tylko wtedy, gdy plik ten nie jest aktualnie
otwarty przez żaden inny proces.
F_UNLCK
Zdjęcie własnej dzierżawy z pliku.
Proces może utrzymywać na pliku dzierżawę tylko jednego typu.
Dzierżawy można pobierać tylko dla zwykłych plików. Proces nieuprzywilejowany może
pobierać jedynie dzierżawy na plikach, których UID odpowiada UID-owi systemu plików dla
danego procesu.
F_GETLEASE
Wskazuje rodzaj dzierżawy utrzymywanej przez aktualny proces na pliku określonym
przez deskryptor fd, zwracając F_RDLCK, F_WRLCK albo F_UNLCK, w zależności od tego,
czy (odpowiednio) aktualny proces utrzymuje dzierżawę odczytu, zapisu, czy nie
utrzymuje żadnej dzierżawy na danym pliku. (Trzeci argument fcntl() jest
pomijany.)
Gdy współzawodnik wykona operację open() lub truncate() kolidującą z dzierżawą ustanowioną
poprzez F_SETLEASE, wywołanie funkcji systemowej jest blokowane przez jądro (chyba że w
open(), podano znacznik O_NONBLOCK kiedy powraca ona natycmiast zgłaszając błąd
EWOULDBLOCK). Jądro zawiadamia wówczas dzierżawcę poprzez wysłanie sygnału (domyślnie
SIGIO). Dzierżawca powinien odpowiedzieć na otrzymanie tego sygnału wykonując porządki
niezbędne dla przygotowania pliku do dostępu przez inny proces (np. zrzucenie buforów) a
następnie usunięcie swojej dzierżawy poprzez wykonanie polecenia F_SETLEASE podając jako
arg F_UNLCK.
Jeśli dzierżawca nie zwolni dzierżawy w ciągu podanej w /proc/sys/fs/lease-break-time
liczby sekund, a wywołanie funkcji systemowej przez współzawodnika pozostaje zablokowane
(tzn. współzawodnik nie podał O_NONBLOCK w swoim wywołaniu funkcji open(), ani też
wywołanie funkcji systemowej nie zostało przerwane przez obsługę sygnału), to jądro wymusi
przerwanie dzierżawy przez dzierżawcę.
Po dobrowolnym lub wymuszonym usunięciu dzierżawy, pzry założeniu, że wywołanie funkcji
systemowej przez współzawodnika nie jest nieblokujące, jądro pozwala na kontynuację
funkcji systemowej wywołanej przez współzawodnika.
Domyślnym sygnałem stosowanym do zawiadamiania dzierżawcy jest SIGIO, lecz można go
zmienić za pomocą polecenia F_SETSIG w fcntl (). Jeśli wydano polecenie F_SETSIG (nawet
podając SIGIO), a funkcja obsługi sygnału została określona za pomocą SA_SIGINFO, to ta
funkcja obsługi otrzyma jako drugi argument strukturę siginfo_t, której pole si_fd będzie
zawierać deskryptor dzierżawionego pliku, do którego uzyskuje dostęp inny proces. (Jest
to przydatne, gdy wywołujący utrzymuje dzierżawy na wielu plikach).
Powiadamianie o zmianach pliku lub katalogu
F_NOTIFY
(od Linuksa 2.4 wzwyż) Zapewnia powiadamianie o modyfikacji katalogu, do którego
odnosi się fd lub o modyfikacji któregokolwiek z plików w tym katalogu. Zdarzenia,
powiadamianie o których ma nastąpić są określone w arg, będącym maską bitową
utworzoną jako suma logiczna (OR) zera lub więcej spośród następujących bitów:
Bit Opis (zdarzenie w katalogu)
──────────────────────────────────────────────────────────
DN_ACCESS Dostęp do pliku (read, pread, readv)
DN_MODIFY Modyfikacja pliku (write, pwrite,
writev, truncate, ftruncate)
DN_CREATE Utworzenie pliku (open, creat, mknod,
mkdir, link, symlink, rename)
DN_DELETE Usunięcie pliku (unlink, rename do
innego katalogu, rmdir)
DN_RENAME Zmiana nazwy w obrębie katalogu
(rename)
DN_ATTRIB Zmiana atrybutów pliku
(chown, chmod, utime[s])
(Uzyskanie ich definicji wymaga zdefiniowania makra _GNU_SOURCE przed włączeniem
<fcntl.h>.)
Powiadomienia dotyczące katalogów są zazwyczaj jednorazowe, więc aplikacja musi się
ponownie zarejestrować, aby otrzymać dalsze powiadomienia. Alternatywnie, jeśli w
arg włączono DN_MULTISHOT, to powiadomienia będą dokonywane aż do ich jawnego
usunięcia. Szereg wywołań podających DN_MULTISHOT kumuluje się, przy czym
zdarzenia w arg są dodawane logicznie do już monitorowanych. Aby wyłączyć
powiadamianie o jakichkolwiek zdarzeniach, należy w wywołaniu F_NOTIFY podać arg
równe 0.
Powiadamianie odbywa się poprzez dostarczenie sygnału. Domyślnym sygnałem jest
SIGIO, ele można go amienić za pomocą polecenia F_SETSIG w fcntl(). W tym drugim
przypadku, funkcja obsługi sygnału otrzymuje jako swój drugi argument strukturę
siginfo_t (gdy funkcja obsługi sygnału została określona za pomocą A_SIGINFO) a
pole si_fd tej struktury zawiera deskryptor pliku, który spowodował powiadomienie.
(przydatne, gdy utrzymywane są dzierżawy na wielu katalogach).
W szczególności, gdy używa się DN_MULTISHOT, do zawiadamiania powinien być
stosowany sygnał czasu rzeczywistego zgodny z POSIX.1b, tak aby mozna było
kolekować wiele zmian.
WARTOŚĆ ZWRACANA
Wartość zwracana po pomyślnym zakończeniu funkcji zależy od operacji:
F_DUPFD Nowy deskryptor.
F_GETFD Wartość znacznika.
F_GETFL Wartości znaczników.
F_GETOWN Wartość właściciela deskryptora.
F_GETSIG Wartość sygnału wysłyanego, gdy odczyt lub zapis staną się możliwe, lub zero, dla
tradycyjnego zachowania SIGIO.
Wszystkie pozostałe polecenia
Zero.
Przy błędach zwracane jest -1 i odpowiednio ustawiane errno.
BŁĘDY
EACCES lub EAGAIN
Operacja jest zabroniona przez blokadę utrzymywaną przez inny proces. Albo,
operacja jest zabroniona, gdyż plik został odwzorowany w pamięci przez inny proces.
EBADF fd nie jest deskryptorem otwartego pliku, albo było to polecenie F_SETLK lub
F_SETLKW a tryb otwarcia deskryptora pliku nie odpowiada rodzajowi żądanej blokady.
EDEADLK
Stwierdzono, że podane polecenie F_SETLKW spowodowałoby zakleszczenie blokad.
EFAULT lock znajduje się poza dostępną dla użytkownika przestrzenią adresową.
EINTR Dla F_SETLKW, oznacza, że polecenie zostało przerwane przez sygnał. Dla F_GETLK i
F_SETLK, polecenie zostało przerwane przez sygnał zanim blokada została sprawdzona
lub ustawiona. Najbardziej prawdopodobne podczas blokowania zdalnego pliku (np.
blokowanie przez NFS), ale czasmi zdaża się lokankie.
EINVAL Dla F_DUPFD, arg jest ujemny, lub większy od maksymalnej dozwolonej wartości. Dla
F_SETSIG, arg nie jest dozwolonym numerem sygnału.
EMFILE Dla F_DUPFD, proces już osiągnął maksymalną liczbę otwartych deskryptorów plików.
ENOLCK Zbyt wiele otwartych blokad segmentowych, tablica blokad jest pełna lub zawiódł
protokół blokowania zdalnego (np. dla blokad przez NFS).
EPERM Próbowano wyzerować znacznik O_APPEND na pliku posiadającym ustawiony atrybut
"append-only".
UWAGI
Błędy zwracane przez dup2 są inne niż zwracane przez F_DUPFD.
Począwszy od jądra 2.0, nie ma oddziaływania pomiędzy typami blokad zakłądanych przez
flock(2) i przez fcntl(2).
POSIX 1003.1-2001 zezwala na ujemne wareości l_len. (I jeśli wartość jest ujemna, to
przedziałem, którego dotyczy blokada obejmuje bajty od l_start+l_len do l_start-1
włącznie.) Jednakże, funkcja systemowa z aktualnych jąder Linuksa zwraca w tej sytuacji
EINVAL.
W niektórych systemach struktura struct flock zawiera dodatkowe pola, takie jak np.
l_sysid. Oczywiście, samo l_pid jest mało przydatne, gdy proces utrzymujący blokadę może
działać na innej maszynie.
ZGODNE Z
SVr4, SVID, POSIX, X/OPEN, BSD 4.3. Tylko operacje F_DUPFD, F_GETFD, F_SETFD, F_GETFL,
F_SETFL, F_GETLK, F_SETLK i F_SETLKW są opisane w POSIX.1. F_GETOWN i F_SETOWN są
BSDizmami niewspieranymi przez SVr4; F_GETSIG i F_SETSIG są specyficzne dla Linuksa.
F_NOTIFY, F_GETLEASE i F_SETLEASE są również specyficzne dla Linuksa. (Uzyskanie ich
definicji wymaga zdefiniowania makra _GNU_SOURCE przed włączeniem <fcntl.h>.) Legalne
znaczniki dla F_GETFL/F_SETFL to te, które są wspierane przez open(2) i są tu różnice
między wymienionymi systemami; O_APPEND, O_NONBLOCK, O_RDONLY, i O_RDWR są opisane w
POSIX.1. SVr4 wspiera wiele innych opcji i znaczników, tutaj nie opisanych.
SVr4 dokumentuje dodatkowe błędy EIO, ENOLINK i EOVERFLOW.
ZOBACZ TAKŻE
dup2(2), flock(2), lockf(3), open(2), socket(2)
Zobacz też locks.txt, mandatory.txt i dnotify.txt w /usr/src/linux/Documentation.
INFORMACJE O TŁUMACZENIU
Powyższe tłumaczenie pochodzi z nieistniejącego już Projektu Tłumaczenia Manuali i może
nie być aktualne. W razie zauważenia różnic między powyższym opisem a rzeczywistym
zachowaniem opisywanego programu lub funkcji, prosimy o zapoznanie się z oryginalną
(angielską) wersją strony podręcznika za pomocą polecenia:
man --locale=C 2 fcntl
Prosimy o pomoc w aktualizacji stron man - więcej informacji można znaleźć pod adresem
http://sourceforge.net/projects/manpages-pl/.