FOPEN(3)

NAME
fopen, _fopen_r - open a file

SYNOPSIS

#include <stdio.h>

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

FILE *_fopen_r(struct _reent *reent, const char *file, const char *mode);

DESCRIPTION

fopen initializes the data structures needed to read or write a file. Specify the file's name as the string at file, and the kind of access you need to the file with the string at mode.

The alternate function _fopen_r is a reentrant version. The extra argument reent is a pointer to a reentrancy structure.

Three fundamental kinds of access are available: read, write, and append. *mode must begin with one of the three characters `r', `w', or `a', to select one of these:

r | Open the file for reading; the operation will fail if the file does not exist, or if the host system does not permit you to read it.
w | Open the file for writing from the beginning of the file: effectively, this always creates a new file. If the file whose name you specified already existed, its old contents are discarded.
a | Open the file for appending data, that is writing from the end of file. When you open a file this way, all data always goes to the current end of file; you cannot change this using fseek.

Some host systems distinguish between ``binary'' and ``text'' files. Such systems may perform data transformations on data written to, or read from, files opened as ``text''. If your system is one of these, then you can append a `b' to any of the three modes above, to specify that you are opening the file as a binary file (the default is to open the file as a text file).

`rb', then, means ``read binary''; `wb', ``write binary''; and `ab', ``append binary''.

To make C programs more portable, the `b' is accepted on all systems, whether or not it makes a difference.

Finally, you might need to both read and write from the same file. You can also append a `+' to any of the three modes, to permit this. (If you want to append both `b' and `+', you can do it in either order: for example, "rb+" means the same thing as "r+b" when used as a mode string.)

Use "r+" (or "rb+") to permit reading and writing anywhere in an existing file, without discarding any data; "w+" (or "wb+") to create a new file (or begin by discarding all data from an old one) that permits reading and writing anywhere in it; and "a+" (or "ab+") to permit reading anywhere in an existing file, but writing only at the end.

RETURNS

fopen returns a file pointer which you can use for other file operations, unless the file you requested could not be opened; in that situation, the result is NULL. If the reason for failure was an invalid string at mode, errno is set to EINVAL.

PORTABILITY

fopen is required by ANSI C.

Supporting OS subroutines required: close, fstat, isatty, lseek, open, read, sbrk, write.

AUTHORS

Steve Chamberlain
    Author.

Roland Pesch
    Author.

Red Hat Support

Jeff Johnston
    Author.

COPYRIGHT

This file documents the ANSI C library.

Copyright (C) 1992, 1993, 1994-2014 Red Hat, Inc.

libc includes software developed by the University of California, Berkeley and its contributors.

libc includes software developed by Martin Jackson, Graham Haley and Steve Chamberlain of Tadpole Technology and released to Cygnus.

libc uses floating-point conversion software developed at AT&T, which includes this copyright information:

The author of this software is David M. Gay.

Copyright (c) 1991 by AT&T.

Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software.

THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, subject to the terms of the GNU General Public License, which includes the provision that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.