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

nazwa
składnia
opis
wartość zwracana
błędy
atrybuty
zgodne z
uwagi
błędy
zobacz także
o stronie
t◈umaczenie

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