table of contents
other sections
FCNTL(2) | Podręcznik programisty Linuksa | FCNTL(2) |
NAZWA¶
fcntl - manipulacje na deskryptorze plikuSKŁ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ę.
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.
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.
- 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.)
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])
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.
- Wszystkie pozostałe polecenia
- Zero.
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
2002-04-24 | Linux-2.5.18 |