FOPEN(3)

NAZWA
fopen, fdopen, freopen - funkcje otwarcia strumienia

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

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.

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