Data Structures | Macros | Typedefs | Enumerations | Functions
files.h File Reference
#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


#define O_BINARY   0
#define O_TEXT   0
#define O_NOFOLLOW   0
#define RFTS_BIN   1
#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))


typedef struct open_file_t open_file_t
typedef struct sized_chunk_t sized_chunk_t


enum  file_status_t {


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)
 MOCK_DECL (int, tor_unlink,(const char *pathname))
file_status_t file_status (const char *filename)
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)
 MOCK_DECL (int, write_str_to_file,(const char *fname, const char *str, int bin))
 MOCK_DECL (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)
 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


#define RFTS_BIN   1

Flag for read_file_to_str: open the file in binary mode.

Definition at line 95 of file files.h.



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

Definition at line 97 of file files.h.

Typedef Documentation

◆ sized_chunk_t

typedef struct sized_chunk_t sized_chunk_t

An ad-hoc type to hold a string of characters and a count; used by write_chunks_to_file.

Enumeration Type Documentation

◆ file_status_t

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

Definition at line 55 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 457 of file files.c.

Referenced by start_writing_to_stdio_file().

◆ 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 538 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().

◆ 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 365 of file files.c.

References open_file_t::binary, open_file_t::fd, open_file_t::stdio_file, and tor_assert().

Referenced by start_writing_to_stdio_file().

◆ 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 212 of file files.c.

Referenced by init_key_from_file(), replace_file(), and write_configuration_file().

◆ 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 449 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 181 of file files.c.

References SIZE_T_CEILING.

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

Definition at line 564 of file files.c.

References SIZE_T_CEILING.

Referenced by get_total_system_memory_impl(), and load_torrc_from_stdin().

◆ 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 117 of file files.c.

References file_status(), and tor_rename().

◆ 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 301 of file files.c.

Referenced by microdescs_add_list_to_cache(), and start_writing_to_stdio_file().

◆ 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 382 of file files.c.

References abort_writing_to_file(), fdopen_file(), and start_writing_to_file().

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

Referenced by dirserv_read_measured_bandwidths(), and geoip_load_file().

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

References sandbox_intern_string.

Referenced by get_total_system_memory_impl(), keypin_open_journal(), and open_and_add_file_log().

◆ tor_rename()

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

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

Definition at line 103 of file files.c.

Referenced by replace_file().

◆ touch_file()

int touch_file ( const char *  fname)

Change fname's modification time to now.

Definition at line 142 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 162 of file files.c.

Referenced by keypin_journal_append_entry().

◆ 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 548 of file files.c.