Ubuntu Manpage: fopen, fdopen, freopen - funkcje otwarcia strumienia

Provided by: manpages-pl-dev_4.23.1-1_all

NAZWA

       fopen, fdopen, freopen - funkcje otwarcia strumienia

BIBLIOTEKA

       Standardowa biblioteka C (libc, -lc)

SKŁADNIA

       #include <stdio.h>

       FILE *fopen(const char *restrict pathname, const char *restrict mode);
       FILE *fdopen(int fd, const char *mode);
       FILE *freopen(const char *restrict pathname, const char *restrict mode,
                     FILE *restrict stream);

   Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)):

       fdopen():
           _POSIX_C_SOURCE

OPIS

Funkcja fopen() otwiera plik, którego nazwę wskazuje pathname i wiąże z nim strumień.

Argument mode wskazuje na łańcuch rozpoczynający się jednym z poniższych ciągów (mogą po
nich występować dodatkowe znaki, zgodnie z opisem poniżej):

r Otwarcie pliku tekstowego do odczytu. Strumień wskazuje początek pliku.

r+ Otwarcie pliku do odczytu i zapisu. Strumień wskazuje początek pliku.

w Usunięcie zawartości pliku lub utworzenie nowego pliku tekstowego do zapisu.
Strumień wskazuje początek pliku.

w+ Otwarcie do odczytu i zapisu. Jeśli plik nie istnieje, zostaje utworzony, w
przeciwnym wypadku jego zawartość zostaje usunięta. Strumień wskazuje początek
pliku.

a Otwarcie do dopisywania (zapisu na końcu pliku). Jeśli plik nie istnieje, zostaje
utworzony. Strumień wskazuje na koniec pliku.

a+ Otwarcie do dopisywania (zapisu na końcu pliku). Jeśli plik nie istnieje, zostaje
utworzony. Wyjście jest zawsze dopisywane na końcu pliku. POSIX milczy na temat
początkowej pozycji odczytu, przy korzystaniu z tego trybu. W przypadku glibc,
początkową pozycją pliku do odczytywania jest początek pliku, lecz
Android/BSD/MacOS ustawiają początkową pozycję pliku do odczytywania na końcu
pliku.

Łańcuch mode może także zawierać literę „b” zarówno jak ostatni znak jak też jako znak
umieszczony pomiędzy znakami dowolnego dwuznakowego łańcucha opisanego powyżej. Służy to
wyłącznie zgodności z ISO C i nie powoduje żadnego efektu, „b” jest ignorowane we
wszystkich systemach zgodnych z POSIX, włączając Linuksa (inne systemy mogą różnie
traktować pliki tekstowe i pliki binarne; dodanie „b” może być dobrym pomysłem, jeśli
wykonywane są operacje wejścia/wyjścia dla pliku binarnego a przewidywane jest
przeniesienie programu do środowisk nieuniksowych).

Więcej informacji o rozszerzeniach glibc dla mode zawarto w UWAGACH.

Odczyt i zapis może występować w strumieniu do zapisu/odczytu w dowolnej kolejności.
Należy zauważyć, że ANSI C wymaga interwencji funkcji ustalającej pozycję pliku pomiędzy
zapisem i odczytem, chyba że operacja odczytu napotka koniec pliku. (Jeśli ten warunek nie
jest spełniony, operacja odczytu może zwrócić wynik innego zapisu niż ostatni.) Tak więc
dobrą zasadą (i czasami konieczną pod Linuksem) jest wstawianie funkcji fseek(3) lub
fsetpos(3) pomiędzy operacjami zapisu i odczytu na takim strumieniu. Ta operacja może być
pozornym rozkazem pustym, no-op, (tak jak w fseek(..., 0L, SEEK_CUR) wywoływanym w celu
wykorzystania ubocznych skutków synchronizujących.

Otwarcie pliku w trybie dopisywania (a jako pierwszy znak mode) powoduje, że wszystkie
późniejsze operacje zapisu do tego strumienia wystąpią na końcu pliku, tak jakby były
poprzedzone wywołaniem

fseek(stream, 0, SEEK_END);

Deskryptor pliku związany ze strumieniem jest otwierany w taki sposób, jak przy wywołaniu
open(2) z następującymi znacznikami:

┌─────────────┬───────────────────────────────┐
│tryb fopen() │ znaczniki open() │
├─────────────┼───────────────────────────────┤
│ r │ O_RDONLY │
├─────────────┼───────────────────────────────┤
│ w │ O_WRONLY | O_CREAT | O_TRUNC │
├─────────────┼───────────────────────────────┤
│ a │ O_WRONLY | O_CREAT | O_APPEND │
├─────────────┼───────────────────────────────┤
│ r+ │ O_RDWR │
├─────────────┼───────────────────────────────┤
│ w+ │ O_RDWR | O_CREAT | O_TRUNC │
├─────────────┼───────────────────────────────┤
│ a+ │ O_RDWR | O_CREAT | O_APPEND │
└─────────────┴───────────────────────────────┘
fdopen()
Funkcja fdopen() wiąże strumień z istniejącym deskryptorem pliku, fd. Łańcuch mode
strumienia (jeden z „r”, „r+”, „w”, „w+”, „a”, „a+”) musi być zgodny z trybem otwarcia
deskryptora pliku. Pozycja nowego strumienia jest taka sama, jak pozycja deskryptora fd, a
znaczniki błędu i końca pliku są wyłączane. Tryby „w” oraz „w+” nie powodują usunięcia
zawartości pliku. Deskryptor pliku nie jest powielany i zostanie zamknięty w chwili
zamknięcia strumienia utworzonego za pomocą fdopen(). Rezultat wywołania funkcji fdopen()
dla obiektu pamięci dzielonej jest niezdefiniowany.

freopen()
Funkcja freopen() otwiera plik, którego nazwa jest zawarta w łańcuchu wskazywanym przez
pathname i wiąże z nim strumień wskazywany przez stream. Pierwotny strumień jest zamykany
(jeśli istnieje). Argument mode ma takie samo znaczenie jak w przypadku funkcji fopen().

Jeśli argument pathname jest wskaźnikiem pustym, freopen() zmienia tryb strumienia na tryb
określony w mode; to jest freopen() otwiera ponownie ścieżkę, która jest związana ze
strumieniem. Określenie tego zachowania zostało dodane w standardzie C99, które opisuje go
następująco:

W takim przypadku, deskryptor pliku związany ze strumieniem nie musi być zamknięty,
jeśli wywołanie do freopen() powiedzie się. Od implementacji zależy, które zmiany
trybów są dozwolone (o ile w ogóle) i w jakich okolicznościach.

Podstawowym zastosowaniem funkcji freopen() jest zmiana pliku związanym ze standardowym
strumieniem tekstowym (stderr, stdin lub stdout).

WARTOŚĆ ZWRACANA

       Jeśli funkcja fopen(), fdopen() czy freopen() zakończy się pomyślnie, zwraca  wskaźnik  do
       struktury  FILE. W przeciwnym wypadku zwraca NULL a zmiennej globalnej errno nadawana jest
       wartość określającą rodzaj błędu.

BŁĘDY

       EINVAL Argument mode podany dla fopen(), fdopen() lub freopen() jest nieprawidłowy.

       Funkcje fopen(), fdopen() i freopen() mogą także zakończyć się  niepowodzeniem  i  ustawić
       wartość errno na dowolny błąd wymieniony w opisie funkcji malloc(3).

       Funkcja fopen() może także zakończyć się niepowodzeniem i ustawić wartość errno na dowolny
       błąd wymieniony w opisie funkcji open(2).

       Funkcja fdopen() może także zakończyć  się  niepowodzeniem  i  ustawić  wartość  errno  na
       dowolny błąd wymieniony w opisie funkcji fcntl(2).

       Funkcja  freopen()  może  także  zakończyć  się  niepowodzeniem i ustawić wartość errno na
       dowolny błąd wymieniony w opisie funkcji open(2), fclose(3) i fflush(3).

ATRYBUTY

       Informacje  o  pojęciach  używanych  w  tym  rozdziale   można   znaleźć   w   podręczniku
       attributes(7).

       ┌────────────────────────────────────────────────┬────────────────────────┬───────────────┐
       │Interfejs                                       │ Atrybut                │ Wartość       │
       ├────────────────────────────────────────────────┼────────────────────────┼───────────────┤
       │fopen(), fdopen(), freopen()                    │ Bezpieczeństwo wątkowe │ MT-bezpieczne │
       └────────────────────────────────────────────────┴────────────────────────┴───────────────┘

STANDARDY

       fopen()
       freopen()
              C11, POSIX.1-2008.

       fdopen()
              POSIX.1-2008.

HISTORIA

       fopen()
       freopen()
              POSIX.1-2001, C89.

       fdopen()
              POSIX.1-2001.

UWAGI

   Uwagi dla glibc
       Biblioteka  GNU  C  umożliwia  stosowanie następujących rozszerzeń dla łańcucha podanego w
       mode:

       c (od glibc 2.3.3)
              W przypadku operacji otwarcia lub kolejnych operacji odczytu  i  zapisu,  nie  robi
              punktów  anulowania  (cancellation  point)  wątku.  Znacznik  ten jest ignorowany w
              przypadku fdopen().

       e (od glibc 2.7)
              Otwiera plik ze znacznikiem O_CLOEXEC. Więcej  informacji  w  podręczniku  open(2).
              Znacznik ten jest ignorowany w przypadku fdopen().

       m (od glibc 2.3)
              Próbuje  uzyskać  dostęp  do  pliku  za pomocą mmap(2), zamiast wywołań systemowych
              wejścia/wyjścia (read(2), write(2)). Obecnie, próba korzystania z  mmap(2)  nastąpi
              tylko, gdy plik jest otwierany do odczytu.

       x      Otwiera  plik  na  wyłączność  (jak  przy znaczniku O_EXCL open(2)). Jeśli plik już
              istnieje, fopen() zawodzi i ustawia errno na EEXIST. Znacznik ten jest ignorowany w
              przypadku fdopen().

       Oprócz  powyższych  znaków,  fopen()  i freopen() obsługują ponadto następującą składnię w
       mode:

        ,ccs=łańcuch

       Podany string jest przyjmowany jako nazwa zakodowanego zestawu  znaków,  a  strumień  jest
       oznaczany  jako  zorientowany  szeroko.  Od  tego momentu, wewnętrzna funkcje konwertujące
       przekształcają wejście/wyjście na i z zestawu znaków string. Jeśli nie użyje  się  składni
       ,ccs=string,  to  szerokie zorientowanie strumienia jest ustalane po pierwszej operacji na
       pliku. Jeśli operacja ta działa na szerokich znakach,  to  strumień  jest  oznaczany  jako
       zorientowany  szeroko  i  ładowane  są  funkcje  służące do konwersji na zakodowany zestaw
       znaków.

USTERKI

       Przy przetwarzaniu mode pod kątem  wyodrębnienia  poszczególnych  znaków  znaczników  (tj.
       znaków   poprzedzających  określenie  „ccs”),  implementacja  glibc  fopen()  i  freopen()
       ogranicza liczbę znaków sprawdzanych w mode do 7 (lub, przed glibc 2.14, do 6, co nie było
       wystarczające   do   uwzględnienia  możliwych  określeń  takich  jak  „rb+cmxe”).  Bieżąca
       implementacja fdopen() sprawdza co najwyżej 5 znaków w mode.

ZOBACZ TAKŻE

       open(2), fclose(3), fileno(3), fmemopen(3), fopencookie(3), open_memstream(3)

TŁUMACZENIE

       Autorami  polskiego  tłumaczenia   niniejszej   strony   podręcznika   są:   Adam   Byrtek
       <alpha@irc.pl>,   Andrzej   Krzysztofowicz   <ankry@green.mf.pg.gda.pl>  i  Michał  Kułach
       <michal.kulach@gmail.com>

       Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe  informacje  o  warunkach  licencji
       można   uzyskać   zapoznając   się   z   GNU   General   Public   License   w   wersji   3
       ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩  lub  nowszej.  Nie   przyjmuje   się   ŻADNEJ
       ODPOWIEDZIALNOŚCI.

       Błędy  w  tłumaczeniu  strony  podręcznika  prosimy  zgłaszać  na  adres listy dyskusyjnej
       ⟨manpages-pl-list@lists.sourceforge.net⟩.