File System

Files
file	dirent.h
file	stdio.h
file	stat.h
file	types.h

Functions
DIR *	opendir (const char *name)
	Open a directory. More...
int	closedir (DIR *dirp)
	Close a directory. More...
struct dirent *	readdir (DIR *dirp)
	Read an entry of a directory. More...
FILE *	fopen (const char *pathname, const char *mode)
	Open a file. More...
int	fclose (FILE *fp)
	Close a file. More...
int	stat (const char *path, struct stat *buf)
	Retrieve metadata of a file. More...
int	lstat (const char *path, struct stat *buf)
	Retrieve metadata of a file. More...

Detailed Description

Checking whether a regular file exists, open it, and close it:

char *file = "./testfile";
  
// get file metadata
struct stat sbuf;
if (lstat(file, &sbuf) == -1){
    perror("lstat");
    exit(EXIT_FAILURE);
}
  
// check file type
if (!S_ISREG(sbuf.st_mode)) {
    fprintf(stderr, "%s is not a regular file.", file);
    exit(EXIT_FAILURE);
}
  
// open file
FILE *fd = fopen(file, "r+");
if (fd == NULL) {
     perror("fopen");
     exit(EXIT_FAILURE);
}
  
// use file
// [...]
  
// close file, check for errors (like full disk)
if (fclose(fd) != 0) {
    perror("fclose");
    exit(EXIT_FAILURE);
}

Iterating over all entries of a directory. Be aware, that readdir() also returns hidden files (starting with a .) including the two entries pointing to the current directory (.) and the parent directory (..).

const char *path = "test/";
  
// open directory
DIR *dir = opendir(path);
if (dir == NULL) {
    perror("opendir");
    exit(EXIT_FAILURE);
}
  
// iterate over directory entries
struct dirent *dirent;
while (errno = 0, (dirent = readdir(dir)) != NULL) {
    printf("%s\n", dirent->d_name);
}
if (errno != 0) {
    perror("readdir");
    exit(EXIT_FAILURE);
}
  
// close directory
closedir(dir);

Function Documentation

opendir()

DIR* opendir

(

const char *

name

)

The opendir() function opens a directory stream according to name. The stream is positioned at the first entry of the directory. Opened directories must be closed by closedir().

Parameters

name	name of the directory to be opened

Return values

DIR*	on success
NULL	on error, errno is set

closedir()

int closedir

(

DIR *

dirp

)

A directory opened by the opendir() function, can be closed by the closedir() function, which frees all allocated resources.

We do not expect error handling when closing directories, so simply do:

closedir(dir);

Parameters

dirp	directory stream to be closed

readdir()

struct dirent* readdir

(

DIR *

dirp

)

The readdir() function reads the next entry from an opened directory stream pointed to by dirp. It allocates a struct dirent structure and returns a pointer to the allocated structure containing the information about the next directory entry. The caller of readdir() must not provide (or free) memory for the struct dirent structure.

readdir() returns NULL if an error occurs or if the end of the directory stream is reached. To be able to distinguish these two events, a caller must set the errno variable to 0 before each call of readdir(). If errno is still 0 after readdir() returned NULL the end of the directory stream has been reached, otherwise an error has occurred.

The struct dirent contains information about a directory entry. The most important information are the inode number and the name of the entry:

struct dirent {
   ino_t          d_ino;       // Inode number
   [...]
   char           d_name[256]; // Null-terminated filename
};

Parameters

dirp	directory stream to read next entry from

Return values

dirent*	pointer to the next directory entry
NULL	on error (errno is set) or if the end of the directory stream is reached

fopen()

FILE* fopen	(	const char *	pathname,
		const char *	mode
	)

The fopen() (file open) function opens the file at pathname with the mode as specified in mode. Opened files must be closed by fclose().

The path in pathname can specify a relative (based on the current working directory) or an absolute path.

Valid file modes are:

Mode	Description
r	read only
r+	read and write
w	write only, create file if it does not exist yet
w+	read and write file, create file if it does not exist yet
a	write only, append only, create file if it does not exist yet
a+	write append only, read from beginning only, create file if it does not exist yet

Parameters

pathname	path to file
mode	file mode

Return values

FILE*	on success
NULL	on error, errno is set

fclose()

int fclose

(

FILE *

fp

)

A file opened by the fopen() function, can be closed with the fclose() (file close) function, which writes all remaining buffered operations to the file and frees all allocated resources.

Parameters

fp	file stream to be closed

Return values

0	on success
EOF	on error, errno is set

stat()

int stat	(	const char *	path,
		struct stat *	buf
	)

The stat() function retrieves information about the file pointed to by path. If path is a symbolic link, stat() returns information about the underlying file instead of the link itself. Be aware that the caller is responsible to provide the memory for the struct stat structure pointed to by buf!

The struct stat contains, amongst others, the following information:

struct stat {
   [...]
   ino_t     st_ino;         // Inode number
   mode_t    st_mode;        // File type and mode
   nlink_t   st_nlink;       // Number of hard links
   uid_t     st_uid;         // User ID of owner
   gid_t     st_gid;         // Group ID of owner
   [...]
   off_t     st_size;        // Total size, in bytes
   [...]
};

The st_mode field encodes the file type and permissions. In order to check whether a file is regular file, a symbolic link, or a directory, some macros exist:

struct stat buf;
stat(pathname, &buf);
[...] // error handling
if (S_ISREG(buf.st_mode)) { printf("regular file"); }
if (S_ISDIR(buf.st_mode)) { printf("directory "); }
if (S_ISLNK(buf.st_mode)) { printf("link"); } // only with lstat()

Parameters

path	file to be analyzed
buf	pointer to a buffer storing the retrieved information

Return values

0	on success
-1	on error, errno is set

lstat()

int lstat	(	const char *	path,
		struct stat *	buf
	)

The lstat() function retrieves information about the file pointed to by path. If path is a symbolic link, lstat() returns information about the link itself instead of the underlying file. Be aware that the caller is responsible to provide the memory for the struct stat structure pointed to by buf!

For more details see the stat() function.

Parameters

path	file to be analyzed
buf	pointer to a buffer storing the retrieved information

Return values

0	on success
-1	on error, errno is set