File management

File pointers

A file in C is a struct from <stdio.h>, declared using the typedef as type FILE

Access to a stream is defined by a FILE* pointer (Multiple file pointers can be defined, although the number of streams is limited by the operating system).

Standard streams

When executing a C program, the operating system must open 3 standard streams and associate them with 3 pointers.

In C, these pointers are already declared by <stdio.h>.

Pointer name	File descriptor	Standard stream type
stdin	0	INPUT
stdout	1	OUTPUT
stderror	2	ERROR

When explicitly referring to one of these 3 streams, it is indifferent to use the pointer name or its file descriptor.

File opening

FILE *fopen(const char * restrict  filename, const char * restrict  mode);

• Returns a pointer to the file named filename opened in mode mode

• Returns NULL if there was an error opening the file

restrict (C99) indicates that name and mode must point to strings that do not share memory locations.

Linking of a file to an open stream

FILE  *freopen(const char * restrict  filename, const char * restrict  mode, FILE * restrict stream);

• Associates a different file with an already open stream (stream) • Returns NULL if there was an error

Usually, the streams to which the file is associated are the standard ones (stdin, stdout, stderr).

Opening mode (mode)

Moode	Name	Description
"r"	Read
"w"	Write
"a"	Append	The new text is added at the end of the existing content in the file
"r+"	Read and Write	Processing starts from the beginning of the file
"w+"	Read and Write	First, it resets the content of the file if it already exists; otherwise, it creates a new file
"a+"	Read and Write	Processing starts from the end of the file (append)

File closing

int fclose(FILE *fp);						

• The argument of fclose must be a file pointer obtained with fopen (or freopen)

• Returns 0 if the file has been closed successfully, otherwise the error code EOF (macro defined in <stdio.h>)

Block files

Read

size_t fread(const void  *p, size_t  sizelem, size_t  n, FILE  *fp);

It returns the number of elements read (< n if an error occurs or EOF is reached)

• p is the pointer to the data buffer to read into from a file

• sizelem is the total size (in BYTES) of the buffer, and thus the maximum amount of data to read

• n is the size (in BYTES) of a single data item being read from the file and stored in the buffer

• fp is the pointer to the file from which data is read

Write

size_t fwrite(const void *buffer, size_t  sizelem, size_t  n, FILE *fp);

It returns the number of elements written (< n if an error occurs)

• buffer is the pointer to the data buffer to be written to the file

• sizelem is the total size (in BYTES) of the buffer, and thus the maximum amount of data to write

• n is the size (in BYTES) of a single data item read from the buffer and written to the file

• fp is the pointer to the file to which the data is written

Random Access

Function	Description
int fgetpos(FILE * restrict stream, fpos_t restrict *pos);	Stores in the variable pointed to by pos the current value of the position indicator of the file associated with stream Returns 0 on success and -1 on failure
int fsetpos(FILE * stream, const fpos_t *pos);	Repositions the file position indicator of the file associated with stream according to the position indicator stored in the variable pointed to by pos Returns 0 on success and -1 on failure
int fseek(FILE *fp, long offset, int origin);	Sets the file position indicator of the file associated with fp using: offset, the number of BYTES to move the position relative to origin (can also be < 0) origin can take 3 values: SEEK_SET — relative to the beginning of the file SEEK_CUR — relative to the current position SEEK_END — relative to the end of the file Returns 0 on success and -1 on failure
void rewind(FILE * stream);	Corresponds to: (void) fseek(stream, 0L, SEEK_SET); Sets the file position indicator of the file pointed to by stream to the beginning of the file
long ftell(FILE* stream);	Returns the current value of the file position indicator for the file pointed to by stream Returns the current offset value on success, and -1 on error

Text files

int fprintf( FILE *fp, const char *format, arg0... argN);

It eeturns the number of variables (specified in the format string and passed as arguments arg0, ..., argN) that are actually written by the function to the file pointed to by fp.

printf(format, arg0,…,argN); = fprintf(stdout,format,arg0,…,argN);

int fscanf( FILE *fp, const char *format, arg0... argN);

It returns the number of variables (specified in the format string and stored at the addresses arg0, ..., argN) that match the format and are actually read by the function from the file pointed to by fp.

scanf(format, ind0,…,indN); = fscanf(stdin,format,ind0,…,indN);

int fgetc(FILE *fp);

• It reads a character from the file pointed to by fp and returns it

• If there is a read error or the end of the file is reached, it returns EOF

int fputc(int c, FILE *fp);

• It writes a character to the file pointed to by fp and returns it

• If there is a write error or the end of the file is reached, it returns EOF

int getc(FILE *fp);

int putc(int c, FILE *fp);

They are identical to fgetc and fputc, but they can be implemented as macros, allowing fp to be evaluated multiple times.

int ungetc(int c, FILE *fp);

• Puts c back into fp, making it available for the next read

char *fgets(char *str, int n, FILE *fp);

• Reads a complete line from the file pointed to by fp

• Returns the read line in str (the string does not include the newline character)

• If there is a read error, it returns NULL

int fputs(const char *s, FILE *fp);									

• Writes the string s to fp (with the addition of a newline)

• Returns a non-negative number if written successfully

• If there is a write error, it returns EOF

File buffering

• Read/writes occur on a buffer in the user address space

• Only when a write buffer is full, it is copied to the storage with a system call write() (This mechanism helps reduce the total number of system calls)

Functions

setvbuf

void setvbuf(FILE * restrict stream, char  * restrict buf, int mode, size_t  size);

Mode	Description
_IONBF	Defines unbuffered I/O. The output information is immediately transferred to the write routines.
_IOLBF	Defines line-buffered I/O. The information is transferred for writing to the device when the newline character '\n' is encountered. buf should point to a buffer of at least size bytes.
_IOFBF	Defines fully buffered I/O. buf should point to a buffer of at least size bytes.

• If buf is NULL, only mode matters, and (except for _IONBF) a new buffer will be allocated during the next read or write operation

• setvbuf() must be called when the stream is not active (or after a call to fflush() or before the first I/O operation on the stream)

setbuffer

void setbuffer(FILE * restrict stream, char  * restrict buf, size_t  size);

is equal to:

(void)  setvbuf( stream, buf, buf ? _IOFBF : _IONBF, size);

setbuf

void setbuf(FILE * restrict stream, char  * restrict buf);

• If buf is NULL, buffering is disabled

• Otherwise, buffering is set with the buffer buf, which must have at least the size BUF_SIZ

is equal to:

(void)  setvbuf( stream, buf, buf ? _IOFBF : _IONBF, BUFSIZE);

setlinebuf

void setlinebuf(FILE * restrict stream);

is equal to:

(void)  setvbuf( stream, (char *) NULL, _IOFBF , 0);

fflush

int fflush(FILE *stream);

• Flushes the buffer associated with the file pointed to by stream

• Returns 0 if the flush is successful

Temporary files

Real-world programs often need to create temporary files (files that exist only as long as the program is running). For example, the C compiler uses many temporary files during compilation.

FILE *tmpfile(void);

• Creates a temporary file (opened in "wb+" mode) that will exist until the file is closed or the program terminates

• Returns the pointer to the created file (to be used later to access the file)

char *tmpnam(char *s);

• Generates a name for a temporary file

• The file name is saved in s and a pointer to the first character of s is returned

• If s is NULL, the file name is saved in a static temporary variable and a pointer to this variable is returned

Example:

char *filename;
filename = tmpnam(NULL);

Operations on files

Modification

int remove(const char *filename);

• Removes the file named filename

• Returns 0 if the removal is successful

• Otherwise, returns a non-zero value

int rename(const char  *oldname, const char  *newname);															

• Renames the file named oldname to newname

• Returns 0 if the renaming is successful

• Otherwise, returns a non-zero value

Error handling

void clearerr(FILE *fp);

It clears the end-of-file and error flags associated with the fp stream

int feof (FILE *fp);

It tests the end-of-file flag for the fp stream.

int ferror (FILE *fp);

It tests the error flag for the fp stream.

int fileno (FILE *fp);

It returns the file descriptor of the fp stream.