fopen(3) Library Functions Manual fopen(3) NAZWA fopen, fdopen, freopen - funkcje otwarcia strumienia BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include 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, ktorego nazwe wskazuje pathname i wiaze z nim strumien. Argument mode wskazuje na lancuch rozpoczynajacy sie jednym z ponizszych ciagow (moga po nich wystepowac dodatkowe znaki, zgodnie z opisem ponizej): r Otwarcie pliku tekstowego do odczytu. Strumien wskazuje poczatek pliku. r+ Otwarcie pliku do odczytu i zapisu. Strumien wskazuje poczatek pliku. w Usuniecie zawartosci pliku lub utworzenie nowego pliku tekstowego do zapisu. Strumien wskazuje poczatek pliku. w+ Otwarcie do odczytu i zapisu. Jesli plik nie istnieje, zostaje utworzony, w przeciwnym wypadku jego zawartosc zostaje usunieta. Strumien wskazuje poczatek pliku. a Otwarcie do dopisywania (zapisu na koncu pliku). Jesli plik nie istnieje, zostaje utworzony. Strumien wskazuje na koniec pliku. a+ Otwarcie do dopisywania (zapisu na koncu pliku). Jesli plik nie istnieje, zostaje utworzony. Wyjscie jest zawsze dopisywane na koncu pliku. POSIX milczy na temat poczatkowej pozycji odczytu, przy korzystaniu z tego trybu. W przypadku glibc, poczatkowa pozycja pliku do odczytywania jest poczatek pliku, lecz Android/BSD/MacOS ustawiaja poczatkowa pozycje pliku do odczytywania na koncu pliku. Lancuch mode moze takze zawierac litere ,,b" zarowno jak ostatni znak jak tez jako znak umieszczony pomiedzy znakami dowolnego dwuznakowego lancucha opisanego powyzej. Sluzy to wylacznie zgodnosci z ISO C i nie powoduje zadnego efektu, ,,b" jest ignorowane we wszystkich systemach zgodnych z POSIX, wlaczajac Linuksa (inne systemy moga roznie traktowac pliki tekstowe i pliki binarne; dodanie ,,b" moze byc dobrym pomyslem, jesli wykonywane sa operacje wejscia/wyjscia dla pliku binarnego a przewidywane jest przeniesienie programu do srodowisk nieuniksowych). Wiecej informacji o rozszerzeniach glibc dla mode zawarto w UWAGACH. Wszystkie pliki beda tworzone z uprawnieniami S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH (0666), zmodyfikowanymi przez wartosc umask procesu (patrz umask(2)). Odczyt i zapis moze wystepowac w strumieniu do zapisu/odczytu w dowolnej kolejnosci. Nalezy zauwazyc, ze ANSI C wymaga interwencji funkcji ustalajacej pozycje pliku pomiedzy zapisem i odczytem, chyba ze operacja odczytu napotka koniec pliku. (Jesli ten warunek nie jest spelniony, operacja odczytu moze zwrocic wynik innego zapisu niz ostatni.) Tak wiec dobra zasada (i czasami konieczna pod Linuksem) jest wstawianie funkcji fseek(3) lub fsetpos(3) pomiedzy operacjami zapisu i odczytu na takim strumieniu. Ta operacja moze byc pozornym rozkazem pustym, no-op, (tak jak w fseek(..., 0L, SEEK_CUR) wywolywanym w celu wykorzystania ubocznych skutkow synchronizujacych. Otwarcie pliku w trybie dopisywania (a jako pierwszy znak mode) powoduje, ze wszystkie pozniejsze operacje zapisu do tego strumienia wystapia na koncu pliku, tak jakby byly poprzedzone wywolaniem fseek(stream, 0, SEEK_END); Deskryptor pliku zwiazany ze strumieniem jest otwierany w taki sposob, jak przy wywolaniu open(2) z nastepujacymi 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() wiaze strumien z istniejacym deskryptorem pliku, fd. Lancuch mode strumienia (jeden z ,,r", ,,r+", ,,w", ,,w+", ,,a", ,,a+") musi byc zgodny z trybem otwarcia deskryptora pliku. Pozycja nowego strumienia jest taka sama, jak pozycja deskryptora fd, a znaczniki bledu i konca pliku sa wylaczane. Tryby ,,w" oraz ,,w+" nie powoduja usuniecia zawartosci pliku. Deskryptor pliku nie jest powielany i zostanie zamkniety w chwili zamkniecia strumienia utworzonego za pomoca fdopen(). Rezultat wywolania funkcji fdopen() dla obiektu pamieci dzielonej jest niezdefiniowany. freopen() Funkcja freopen() otwiera plik, ktorego nazwa jest zawarta w lancuchu wskazywanym przez pathname i wiaze z nim strumien wskazywany przez stream. Pierwotny strumien jest zamykany (jesli istnieje). Argument mode ma takie samo znaczenie jak w przypadku funkcji fopen(). Jesli argument pathname jest wskaznikiem pustym, freopen() zmienia tryb strumienia na tryb okreslony w mode; to jest freopen() otwiera ponownie sciezke, ktora jest zwiazana ze strumieniem. Okreslenie tego zachowania zostalo dodane w standardzie C99, ktore opisuje go nastepujaco: W takim przypadku, deskryptor pliku zwiazany ze strumieniem nie musi byc zamkniety, jesli wywolanie do freopen() powiedzie sie. Od implementacji zalezy, ktore zmiany trybow sa dozwolone (o ile w ogole) i w jakich okolicznosciach. Podstawowym zastosowaniem funkcji freopen() jest zmiana pliku zwiazanym ze standardowym strumieniem tekstowym (stderr, stdin lub stdout). WARTOSC ZWRACANA Jesli funkcja fopen(), fdopen() czy freopen() zakonczy sie pomyslnie, zwraca wskaznik do struktury FILE. W przeciwnym wypadku zwraca NULL a zmiennej globalnej errno nadawana jest wartosc okreslajaca rodzaj bledu. BLEDY EINVAL Argument mode podany dla fopen(), fdopen() lub freopen() jest nieprawidlowy. Funkcje fopen(), fdopen() i freopen() moga takze zakonczyc sie niepowodzeniem i ustawic wartosc errno na dowolny blad wymieniony w opisie funkcji malloc(3). Funkcja fopen() moze takze zakonczyc sie niepowodzeniem i ustawic wartosc errno na dowolny blad wymieniony w opisie funkcji open(2). Funkcja fdopen() moze takze zakonczyc sie niepowodzeniem i ustawic wartosc errno na dowolny blad wymieniony w opisie funkcji fcntl(2). Funkcja freopen() moze takze zakonczyc sie niepowodzeniem i ustawic wartosc errno na dowolny blad wymieniony w opisie funkcji open(2), fclose(3) i fflush(3). ATRYBUTY Informacje o pojeciach uzywanych w tym rozdziale mozna znalezc w podreczniku attributes(7). +---------------------------+--------------------------+---------------+ |Interfejs | Atrybut | Wartosc | +---------------------------+--------------------------+---------------+ |fopen(), fdopen(), | Bezpieczenstwo watkowe | MT-bezpieczne | |freopen() | | | +---------------------------+--------------------------+---------------+ 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 umozliwia stosowanie nastepujacych rozszerzen dla lancucha podanego w mode: c (od glibc 2.3.3) W przypadku operacji otwarcia lub kolejnych operacji odczytu i zapisu, nie robi punktow anulowania (cancellation point) watku. Znacznik ten jest ignorowany w przypadku fdopen(). e (od glibc 2.7) Otwiera plik ze znacznikiem O_CLOEXEC. Wiecej informacji w podreczniku open(2). Znacznik ten jest ignorowany w przypadku fdopen(). m (od glibc 2.3) Probuje uzyskac dostep do pliku za pomoca mmap(2), zamiast wywolan systemowych wejscia/wyjscia (read(2), write(2)). Obecnie, proba korzystania z mmap(2) nastapi tylko, gdy plik jest otwierany do odczytu. x Otwiera plik na wylacznosc (jak przy znaczniku O_EXCL open(2)). Jesli plik juz istnieje, fopen() zawodzi i ustawia errno na EEXIST. Znacznik ten jest ignorowany w przypadku fdopen(). Oprocz powyzszych znakow, fopen() i freopen() obsluguja ponadto nastepujaca skladnie w mode: ,ccs=lancuch Podany string jest przyjmowany jako nazwa zakodowanego zestawu znakow, a strumien jest oznaczany jako zorientowany szeroko. Od tego momentu, wewnetrzna funkcje konwertujace przeksztalcaja wejscie/wyjscie na i z zestawu znakow string. Jesli nie uzyje sie skladni ,ccs=string, to szerokie zorientowanie strumienia jest ustalane po pierwszej operacji na pliku. Jesli operacja ta dziala na szerokich znakach, to strumien jest oznaczany jako zorientowany szeroko i ladowane sa funkcje sluzace do konwersji na zakodowany zestaw znakow. USTERKI Przy przetwarzaniu mode pod katem wyodrebnienia poszczegolnych znakow znacznikow (tj. znakow poprzedzajacych okreslenie ,,ccs"), implementacja glibc fopen() i freopen() ogranicza liczbe znakow sprawdzanych w mode do 7 (lub, przed glibc 2.14, do 6, co nie bylo wystarczajace do uwzglednienia mozliwych okreslen takich jak ,,rb+cmxe"). Biezaca implementacja fdopen() sprawdza co najwyzej 5 znakow w mode. ZOBACZ TAKZE open(2), fclose(3), fileno(3), fmemopen(3), fopencookie(3), open_memstream(3) TLUMACZENIE Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: Adam Byrtek , Andrzej Krzysztofowicz i Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.9.1 2 maja 2024 r. fopen(3)