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

NAZWA

       fopen, fdopen, freopen - funkcje otwarcia strumienia

SKŁADNIA

       #include <stdio.h>

       FILE *fopen(const char *pathname, const char *mode);

       FILE *fdopen(int fd, const char *mode);

       FILE *freopen(const char *pathname, const char *mode, FILE *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ń.

The argument mode points to a string beginning with one of the following sequences
(possibly followed by additional characters, as described below):

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+ Open for reading and appending (writing at end of file). The file is created if it
does not exist. Output is always appended to the end of the file. POSIX is silent
on what the initial read position is when using this mode. For glibc, the initial
file position for reading is at the beginning of the file, but for
Android/BSD/MacOS, the initial file position for reading is at the end of the file.

Łańcuch mode może także zawierać literę 'b' zarówno jak ostatni znak jak też jako znak
umeszczony pomiędzy znakami dowolnego dwuznakowego łańcucha opisanego powyżej. Służy to
wyłącznie zgodności z C89 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 I/O dla pliku binarnego a przewidywane jest przeniesienie programu do środowisk
nieuniksowych.)

See NOTES below for details of glibc extensions for mode.

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
fgetpos(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);

The file descriptor associated with the stream is opened as if by a call to open(2) with
the following flags:

┌─────────────┬───────────────────────────────┐
│fopen() mode │ open() flags │
├─────────────┼───────────────────────────────┤
│ 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 zozstanie 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().

If the pathname argument is a null pointer, freopen() changes the mode of the stream to
that specified in mode; that is, freopen() reopens the pathname that is associated with
the stream. The specification for this behavior was added in the C99 standard, which
says:

In this case, the file descriptor associated with the stream need not be closed if
the call to freopen() succeeds. It is implementation-defined which changes of
mode are permitted (if any), and under what circumstances.

The primary use of the freopen() function is to change the file associated with a
standard text stream (stderr, stdin, or 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 open(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-Safe │
       └─────────────────────────────┴────────────────────────┴─────────┘

ZGODNE Z

       fopen(), freopen(): POSIX.1-2001, POSIX.1-2008, C89, C99.

       fdopen(): POSIX.1-2001, POSIX.1-2008.

UWAGI

   Uwagi dla glibc
       The GNU C library allows the following extensions for the string specified in mode:

       c (od wersji 2.3.3 biblioteki glibc)
              Do not make the open operation, or subsequent read  and  write  operations,  thread
              cancellation points.  This flag is ignored for fdopen().

       e (od wersji 2.7 biblioteki glibc)
              Open  the  file  with the O_CLOEXEC flag.  See open(2)  for more information.  This
              flag is ignored for fdopen().

       m (od wersji 2.3 biblioteki glibc)
              Attempt to access the file using mmap(2), rather than I/O  system  calls  (read(2),
              write(2)).   Currently,  use  of  mmap(2)   is attempted only for a file opened for
              reading.

       x      Open the file exclusively (like the O_EXCL flag of open(2)).  If the  file  already
              exists,  fopen()   fails,  and  sets  errno  to  EEXIST.   This flag is ignored for
              fdopen().

       In addition to the above characters, fopen()  and freopen()  support the following  syntax
       in mode:

        ,ccs=string

       The given string is taken as the name of a coded character set and the stream is marked as
       wide-oriented.  Thereafter, internal conversion functions convert  I/O  to  and  from  the
       character   set   string.    If   the  ,ccs=string  syntax  is  not  specified,  then  the
       wide-orientation of the stream is  determined  by  the  first  file  operation.   If  that
       operation is a wide-character operation, the stream is marked wide-oriented, and functions
       to convert to the coded character set are loaded.

BŁĘDY

       When parsing for individual flag characters in mode (i.e., the  characters  preceding  the
       "ccs" specification), the glibc implementation of fopen() and freopen()  limits the number
       of characters examined in mode to 7 (or, in glibc versions before 2.14, to  6,  which  was
       not   enough   to  include  possible  specifications  such  as  "rb+cmxe").   The  current
       implementation of fdopen()  parses at most 5 characters in mode.

ZOBACZ TAKŻE

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

O STRONIE

       Angielska wersja tej strony  pochodzi  z  wydania  5.10  projektu  Linux  man-pages.  Opis
       projektu,  informacje  dotyczące  zgłaszania  błędów oraz najnowszą wersję oryginału można
       znaleźć pod adresem https://www.kernel.org/doc/man-pages/.

T◈UMACZENIE

       Autorami  polskiego  tłumaczenia   niniejszej   strony   podręcznika   są:   Adam   Byrtek
       <alpha@irc.pl> i Andrzej Krzysztofowicz <ankry@green.mf.pg.gda.pl>

       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⟩.