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

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.

Wszystkie pliki będą tworzone z uprawnieniami S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH (0666), zmodyfikowanymi przez wartość umask procesu (patrz umask(2)).

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:

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

STANDARDY

fopen()

freopen()

C11, POSIX.1-2008.

fdopen()

POSIX.1-2008.

HISTORIA

fopen()

freopen()

POSIX.1-2001, C89.

fdopen()

POSIX.1-2001.

UWAGI

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