files.h File Reference

Wrappers for reading and writing data to files on disk. More...

#include "lib/cc/compat_compiler.h"
#include "lib/cc/torint.h"
#include "lib/testsupport/testsupport.h"
#include <stddef.h>
#include <stdio.h>

Go to the source code of this file.

Data Structures
struct	sized_chunk_t

Macros
#define	O_BINARY   0
#define	O_TEXT   0
#define	O_NOFOLLOW   0
#define	OPEN_FLAGS_REPLACE   (O_WRONLY|O_CREAT|O_TRUNC)
#define	OPEN_FLAGS_APPEND   (O_WRONLY|O_CREAT|O_APPEND)
#define	OPEN_FLAGS_DONT_REPLACE   (O_CREAT|O_EXCL|O_APPEND|O_WRONLY)
#define	RFTS_BIN   1
#define	RFTS_IGNORE_MISSING   2
#define	tor_getdelim(lineptr, n, delim, stream)    compat_getdelim_((lineptr), (n), (delim), (stream))
#define	tor_getline(lineptr, n, stream)    tor_getdelim((lineptr), (n), '\n', (stream))

Enumerations
enum	file_status_t {   FN_ERROR , FN_NOENT , FN_FILE , FN_DIR ,   FN_EMPTY }

Functions
int	tor_open_cloexec (const char *path, int flags, unsigned mode)
FILE *	tor_fopen_cloexec (const char *path, const char *mode)
int	tor_rename (const char *path_old, const char *path_new)
int	replace_file (const char *from, const char *to)
int	touch_file (const char *fname)
int	tor_unlink (const char *pathname)
file_status_t	file_status (const char *filename)
bool	is_file (file_status_t file_type)
bool	is_dir (file_status_t file_type)
int64_t	tor_get_avail_disk_space (const char *path)
ssize_t	write_all_to_fd (int fd, const char *buf, size_t count)
ssize_t	read_all_from_fd (int fd, char *buf, size_t count)
int	start_writing_to_file (const char *fname, int open_flags, int mode, open_file_t **data_out)
FILE *	start_writing_to_stdio_file (const char *fname, int open_flags, int mode, open_file_t **data_out)
FILE *	fdopen_file (open_file_t *file_data)
int	finish_writing_to_file (open_file_t *file_data)
int	abort_writing_to_file (open_file_t *file_data)
int	write_str_to_file (const char *fname, const char *str, int bin)
int	write_bytes_to_file (const char *fname, const char *str, size_t len, int bin)
int	write_chunks_to_file (const char *fname, const struct smartlist_t *chunks, int bin, int no_tempfile)
int	append_bytes_to_file (const char *fname, const char *str, size_t len, int bin)
int	write_bytes_to_new_file (const char *fname, const char *str, size_t len, int bin)
int	write_str_to_file_if_not_equal (const char *fname, const char *str)
	MOCK_DECL_ATTR (char *, read_file_to_str,(const char *filename, int flags, struct stat *stat_out), ATTR_MALLOC)
char *	read_file_to_str_until_eof (int fd, size_t max_bytes_to_read, size_t *sz_out) ATTR_MALLOC
ssize_t	compat_getdelim_ (char **lineptr, size_t *n, int delim, FILE *stream)

Detailed Description

Wrappers for reading and writing data to files on disk.

Header for files.c.

Definition in file files.h.

Macro Definition Documentation

O_BINARY

#define O_BINARY   0

Definition at line 37 of file files.h.

O_NOFOLLOW

#define O_NOFOLLOW   0

Definition at line 43 of file files.h.

O_TEXT

#define O_TEXT   0

Definition at line 40 of file files.h.

OPEN_FLAGS_APPEND

#define OPEN_FLAGS_APPEND   (O_WRONLY|O_CREAT|O_APPEND)

Definition at line 71 of file files.h.

OPEN_FLAGS_DONT_REPLACE

#define OPEN_FLAGS_DONT_REPLACE   (O_CREAT|O_EXCL|O_APPEND|O_WRONLY)

Definition at line 72 of file files.h.

OPEN_FLAGS_REPLACE

#define OPEN_FLAGS_REPLACE   (O_WRONLY|O_CREAT|O_TRUNC)

Definition at line 70 of file files.h.

RFTS_BIN

#define RFTS_BIN   1

Flag for read_file_to_str: open the file in binary mode.

Definition at line 103 of file files.h.

RFTS_IGNORE_MISSING

#define RFTS_IGNORE_MISSING   2

Flag for read_file_to_str: it's okay if the file doesn't exist.

Definition at line 105 of file files.h.

tor_getdelim

#define tor_getdelim	(		lineptr,
			n,
			delim,
			stream
	)		compat_getdelim_((lineptr), (n), (delim), (stream))

Definition at line 135 of file files.h.

tor_getline

#define tor_getline	(		lineptr,
			n,
			stream
	)		tor_getdelim((lineptr), (n), '\n', (stream))

Definition at line 149 of file files.h.

Enumeration Type Documentation

file_status_t

enum file_status_t

Return values from file_status(); see that function's documentation for details.

Definition at line 59 of file files.h.

Function Documentation

abort_writing_to_file()

int abort_writing_to_file

(

open_file_t *

file_data

)

Finish writing to file_data: close the file handle, free memory as needed, and if using a temporary file, delete it.

Definition at line 474 of file files.c.

append_bytes_to_file()

int append_bytes_to_file	(	const char *	fname,
		const char *	str,
		size_t	len,
		int	bin
	)

As write_bytes_to_file, but if the file already exists, append the bytes to the end of the file instead of overwriting it.

Definition at line 555 of file files.c.

compat_getdelim_()

ssize_t compat_getdelim_	(	char **	lineptr,
		size_t *	n,
		int	delim,
		FILE *	stream
	)

Internal back-end function to implement getdelim(): only exists when Tor is built for unit tests, or when Tor is built on an operating system without its own getdelim().

Definition at line 38 of file getdelim.c.

fdopen_file()

FILE * fdopen_file

(

open_file_t *

file_data

)

Given file_data from start_writing_to_file(), return a stdio FILE* that can be used to write to the same file. The caller should not mix stdio calls with non-stdio calls.

Definition at line 382 of file files.c.

file_status()

file_status_t file_status

(

const char *

fname

)

Return: FN_ERROR if filename can't be read, is NULL, or is zero-length, FN_NOENT if it doesn't exist, FN_FILE if it is a non-empty regular file, or a FIFO on unix-like systems, FN_EMPTY for zero-byte regular files, FN_DIR if it's a directory, and FN_ERROR for any other file type. On FN_ERROR and FN_NOENT, sets errno. (errno is not set when FN_ERROR is returned due to an unhandled file type.)

Definition at line 213 of file files.c.

finish_writing_to_file()

int finish_writing_to_file

(

open_file_t *

file_data

)

Finish writing to file_data: close the file handle, free memory as needed, and if using a temporary file, replace the original file with the temporary file.

Definition at line 466 of file files.c.

is_dir()

bool is_dir

(

file_status_t

file_type

)

Returns true if file_type represents an existing directory. Returns false otherwise.

Definition at line 262 of file files.c.

is_file()

bool is_file

(

file_status_t

file_type

)

Returns true if file_type represents an existing file (even if empty). Returns false otherwise.

Definition at line 254 of file files.c.

read_all_from_fd()

ssize_t read_all_from_fd	(	int	fd,
		char *	buf,
		size_t	count
	)

Read from fd to buf, until we get count bytes or reach the end of the file. Return the number of bytes read, or -1 on error. Only use if fd is a blocking fd.

Definition at line 182 of file files.c.

read_file_to_str_until_eof()

char * read_file_to_str_until_eof	(	int	fd,
		size_t	max_bytes_to_read,
		size_t *	sz_out
	)

Read the contents of the open file fd presuming it is a FIFO (or similar) file descriptor for which the size of the file isn't known ahead of time. Return NULL on failure, and a NUL-terminated string on success. On success, set sz_out to the number of bytes read (not including the final NULL, which wasn't read from fd).

Definition at line 582 of file files.c.

replace_file()

int replace_file	(	const char *	from,
		const char *	to
	)

Rename the file from to the file to. On Unix, this is the same as rename(2). On windows, this removes to first if it already exists. Returns 0 on success. Returns -1 and sets errno on failure.

Definition at line 118 of file files.c.

start_writing_to_file()

int start_writing_to_file	(	const char *	fname,
		int	open_flags,
		int	mode,
		open_file_t **	data_out
	)

Try to start writing to the file in fname, passing the flags open_flags to the open() syscall, creating the file (if needed) with access value mode. If the O_APPEND flag is set, we append to the original file. Otherwise, we open a new temporary file in the same directory, and either replace the original or remove the temporary file when we're done.

Return the fd for the newly opened file, and store working data in *data_out. The caller should not close the fd manually: instead, call finish_writing_to_file() or abort_writing_to_file(). Returns -1 on failure.

NOTE: When not appending, the flags O_CREAT and O_TRUNC are treated as true and the flag O_EXCL is treated as false.

NOTE: Ordinarily, O_APPEND means "seek to the end of the file before each write()". We don't do that.

Definition at line 318 of file files.c.

start_writing_to_stdio_file()

FILE * start_writing_to_stdio_file	(	const char *	fname,
		int	open_flags,
		int	mode,
		open_file_t **	data_out
	)

Combines start_writing_to_file with fdopen_file(): arguments are as for start_writing_to_file, but

Definition at line 399 of file files.c.

tor_fopen_cloexec()

FILE * tor_fopen_cloexec	(	const char *	path,
		const char *	mode
	)

As fopen(path,mode), but ensures that the O_CLOEXEC bit is set on the underlying file handle.

Definition at line 86 of file files.c.

tor_get_avail_disk_space()

int64_t tor_get_avail_disk_space

(

const char *

path

)

Return the amount of free disk space we have permission to use, in bytes. Return -1 if the amount of free space can't be determined.

Definition at line 28 of file freespace.c.

tor_open_cloexec()

int tor_open_cloexec	(	const char *	path,
		int	flags,
		unsigned	mode
	)

As open(path, flags, mode), but return an fd with the close-on-exec mode set.

Definition at line 54 of file files.c.

tor_rename()

int tor_rename	(	const char *	path_old,
		const char *	path_new
	)

As rename(), but work correctly with the sandbox.

Definition at line 104 of file files.c.

tor_unlink()

int tor_unlink

(

const char *

pathname

)

Wrapper for unlink() to make it mockable for the test suite; returns 0 if unlinking the file succeeded, -1 and sets errno if unlinking fails.

Definition at line 155 of file files.c.

touch_file()

int touch_file

(

const char *

fname

)

Change fname's modification time to now.

Definition at line 143 of file files.c.

write_all_to_fd()

ssize_t write_all_to_fd	(	int	fd,
		const char *	buf,
		size_t	count
	)

Write count bytes from buf to fd. Return the number of bytes written, or -1 on error. Only use if fd is a blocking fd.

Definition at line 163 of file files.c.

write_bytes_to_file()

int write_bytes_to_file	(	const char *	fname,
		const char *	str,
		size_t	len,
		int	bin
	)

As write_str_to_file, but does not assume a NUL-terminated string. Instead, we write len bytes, starting at str.

Definition at line 546 of file files.c.

write_bytes_to_new_file()

int write_bytes_to_new_file	(	const char *	fname,
		const char *	str,
		size_t	len,
		int	bin
	)

Like write_str_to_file(), but also return -1 if there was a file already residing in fname.

Definition at line 565 of file files.c.

write_str_to_file()

int write_str_to_file	(	const char *	fname,
		const char *	str,
		int	bin
	)

Create a file named fname with the contents str. Overwrite the previous fname if possible. Return 0 on success, -1 on failure.

This function replaces the old file atomically, if possible. This function, and all other functions in util.c that create files, create them with mode 0600.

Definition at line 275 of file files.c.

write_str_to_file_if_not_equal()

int write_str_to_file_if_not_equal	(	const char *	fname,
		const char *	str
	)

Attempt to read a file fname. If the file's contents is equal to the string str, return 0. Otherwise, attempt to overwrite the file with the contents of str and return the value of write_str_to_file().

Definition at line 745 of file files.c.