mirror/transmission
1
0
Fork 0
mirror of https://github.com/transmission/transmission synced 2025-02-23 06:30:38 +00:00
Code Issues Releases Wiki Activity
transmission/libtransmission/file.h
Mike Gelfand 650db1f46e #5802: Don't make assumptions of remote path validity in transmission-remote 
Defer validity checks until path gets to the remote side, where they
actually make sense. Add simple checks for download directory path to
ensure it's not relative, since one cannot know what current working
directory of the remote process is.
2015-10-20 21:22:19 +00:00

694 lines
28 KiB
C
Raw Blame History

/*
* This file Copyright (C) 2013-2014 Mnemosyne LLC
*
* It may be used under the GNU GPL versions 2 or 3
* or any future license endorsed by Mnemosyne LLC.
*
* $Id$
*/
#ifndef TR_FILE_H
#define TR_FILE_H
#include <inttypes.h>
#include <time.h>
#ifdef _WIN32
#include <windows.h>
#endif
#ifdef __cplusplus
extern "C" {
#endif
struct tr_error;
/**
* @addtogroup file_io File IO
* @{
*/
#ifndef _WIN32
/** @brief Platform-specific file descriptor type. */
typedef int tr_sys_file_t;
/** @brief Platform-specific invalid file descriptor constant. */
#define TR_BAD_SYS_FILE (-1)
/** @brief Platform-specific directory descriptor type. */
typedef void * tr_sys_dir_t;
/** @brief Platform-specific end-of-line sequence. */
#define TR_NATIVE_EOL_STR "\n"
/** @brief Platform-specific end-of-line sequence length. */
#define TR_NATIVE_EOL_STR_SIZE 1
#else
typedef HANDLE tr_sys_file_t;
#define TR_BAD_SYS_FILE INVALID_HANDLE_VALUE
typedef struct tr_sys_dir_win32 * tr_sys_dir_t;
#define TR_NATIVE_EOL_STR "\r\n"
#define TR_NATIVE_EOL_STR_SIZE 2
#endif
/** @brief Platform-specific invalid directory descriptor constant. */
#define TR_BAD_SYS_DIR ((tr_sys_dir_t)NULL)
typedef enum
{
TR_STD_SYS_FILE_IN,
TR_STD_SYS_FILE_OUT,
TR_STD_SYS_FILE_ERR
}
tr_std_sys_file_t;
typedef enum
{
TR_SYS_FILE_READ = 1 << 0,
TR_SYS_FILE_WRITE = 1 << 1,
TR_SYS_FILE_CREATE = 1 << 2,
TR_SYS_FILE_CREATE_NEW = 1 << 3,
TR_SYS_FILE_APPEND = 1 << 4,
TR_SYS_FILE_TRUNCATE = 1 << 5,
TR_SYS_FILE_SEQUENTIAL = 1 << 6
}
tr_sys_file_open_flags_t;
typedef enum
{
TR_SEEK_SET,
TR_SEEK_CUR,
TR_SEEK_END
}
tr_seek_origin_t;
typedef enum
{
TR_SYS_PATH_NO_FOLLOW = 1 << 0
}
tr_sys_path_get_info_flags_t;
typedef enum
{
TR_SYS_FILE_PREALLOC_SPARSE = 1 << 0
}
tr_sys_file_preallocate_flags_t;
typedef enum
{
TR_SYS_DIR_CREATE_PARENTS = 1 << 0
}
tr_sys_dir_create_flags_t;
typedef enum
{
TR_SYS_PATH_IS_FILE,
TR_SYS_PATH_IS_DIRECTORY,
TR_SYS_PATH_IS_OTHER
}
tr_sys_path_type_t;
typedef struct tr_sys_path_info
{
tr_sys_path_type_t type;
uint64_t size;
time_t last_modified_at;
}
tr_sys_path_info;
/**
* @name Platform-specific wrapper functions
*
* Following functions accept paths in UTF-8 encoding and convert them to native
* encoding internally if needed.
* Descriptors returned (@ref tr_sys_file_t and @ref tr_sys_dir_t) may have
* different type depending on platform and should generally not be passed to
* native functions, but to wrapper functions instead.
*
* @{
*/
/* Path-related wrappers */
/**
* @brief Portability wrapper for `stat ()`.
*
* @param[in] path Path to file or directory.
* @param[in] flags Combination of @ref tr_sys_path_get_info_flags_t values.
* @param[out] info Result buffer.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_path_get_info (const char * path,
int flags,
tr_sys_path_info * info,
struct tr_error ** error);
/**
* @brief Portability wrapper for `access ()`.
*
* @param[in] path Path to file or directory.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` if path exists, `false` otherwise. Note that `false` will also
* be returned in case of error; if you need to distinguish the two,
* check if `error` is `NULL` afterwards.
*/
bool tr_sys_path_exists (const char * path,
struct tr_error ** error);
/**
* @brief Check whether path is relative.
*
* This function only analyzes the string, so no error reporting is needed.
*
* @param[in] path Path to file or directory.
*
* @return `True` if path is relative, `false` otherwise
*/
bool tr_sys_path_is_relative (const char * path);
/**
* @brief Test to see if the two filenames point to the same file.
*
* @param[in] path1 Path to first file or directory.
* @param[in] path2 Path to second file or directory.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` if two paths point to the same file or directory, `false`
* otherwise. Note that `false` will also be returned in case of error;
* if you need to distinguish the two, check if `error` is `NULL`
* afterwards.
*/
bool tr_sys_path_is_same (const char * path1,
const char * path2,
struct tr_error ** error);
/**
* @brief Portability wrapper for `realpath ()`.
*
* @param[in] path Path to file or directory.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return Pointer to newly allocated buffer containing full path (with symbolic
* links, `.` and `..` resolved) on success (use @ref tr_free to free it
* when no longer needed), `NULL` otherwise (with `error` set
* accordingly).
*/
char * tr_sys_path_resolve (const char * path,
struct tr_error ** error);
/**
* @brief Portability wrapper for `basename ()`.
*
* @param[in] path Path to file or directory.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return Pointer to newly allocated buffer containing base name (last path
* component; parent path removed) on success (use @ref tr_free to free
* it when no longer needed), `NULL` otherwise (with `error` set
* accordingly).
*/
char * tr_sys_path_basename (const char * path,
struct tr_error ** error);
/**
* @brief Portability wrapper for `dirname ()`.
*
* @param[in] path Path to file or directory.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return Pointer to newly allocated buffer containing directory (parent path;
* last path component removed) on success (use @ref tr_free to free it
* when no longer needed), `NULL` otherwise (with `error` set
* accordingly).
*/
char * tr_sys_path_dirname (const char * path,
struct tr_error ** error);
/**
* @brief Portability wrapper for `rename ()`.
*
* @param[in] src_path Path to source file or directory.
* @param[in] dst_path Path to destination file or directory.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you
* are not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
* Rename will generally only succeed if both source and destination are
* on the same partition.
*/
bool tr_sys_path_rename (const char * src_path,
const char * dst_path,
struct tr_error ** error);
/**
* @brief Portability wrapper for `remove ()`.
*
* @param[in] path Path to file or directory.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
* Directory removal will only succeed if it is empty (contains no other
* files and directories).
*/
bool tr_sys_path_remove (const char * path,
struct tr_error ** error);
/* File-related wrappers */
/**
* @brief Get handle to one of standard I/O files.
*
* @param[in] std_file Standard file identifier.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you
* are not interested in error details.
*
* @return Opened file descriptor on success, `TR_BAD_SYS_FILE` otherwise (with
* `error` set accordingly). DO NOT pass this descriptor to
* @ref tr_sys_file_close (unless you know what you are doing).
*/
tr_sys_file_t tr_sys_file_get_std (tr_std_sys_file_t std_file,
struct tr_error ** error);
/**
* @brief Portability wrapper for `open ()`.
*
* @param[in] path Path to file.
* @param[in] flags Combination of @ref tr_sys_file_open_flags_t values.
* @param[in] permissions Permissions to create file with (in case
@ref TR_SYS_FILE_CREATE is used). Not used on Windows.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you
* are not interested in error details.
*
* @return Opened file descriptor on success, `TR_BAD_SYS_FILE` otherwise (with
* `error` set accordingly).
*/
tr_sys_file_t tr_sys_file_open (const char * path,
int flags,
int permissions,
struct tr_error ** error);
/**
* @brief Portability wrapper for `mkstemp ()`.
*
* @param[in,out] path_template Template path to file. Should end with at least
* six 'X' characters. Upon success, trailing 'X'
* characters are replaced with actual random
* characters used to form a unique path to
* temporary file.
* @param[out] error Pointer to error object. Optional, pass `NULL`
* if you are not interested in error details.
*
* @return Opened file descriptor on success, `TR_BAD_SYS_FILE` otherwise (with
* `error` set accordingly).
*/
tr_sys_file_t tr_sys_file_open_temp (char * path_template,
struct tr_error ** error);
/**
* @brief Portability wrapper for `close ()`.
*
* @param[in] handle Valid file descriptor.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_close (tr_sys_file_t handle,
struct tr_error ** error);
/**
* @brief Portability wrapper for `fstat ()`.
*
* @param[in] handle Valid file descriptor.
* @param[out] info Result buffer.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_get_info (tr_sys_file_t handle,
tr_sys_path_info * info,
struct tr_error ** error);
/**
* @brief Portability wrapper for `lseek ()`.
*
* @param[in] handle Valid file descriptor.
* @param[in] offset Relative file offset in bytes to seek to.
* @param[in] origin Offset origin.
* @param[out] new_offset New offset in bytes from beginning of file. Optional,
* pass `NULL` if you are not interested.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you
* are not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_seek (tr_sys_file_t handle,
int64_t offset,
tr_seek_origin_t origin,
uint64_t * new_offset,
struct tr_error ** error);
/**
* @brief Portability wrapper for `read ()`.
*
* @param[in] handle Valid file descriptor.
* @param[out] buffer Buffer to store read data to.
* @param[in] size Number of bytes to read.
* @param[out] bytes_read Number of bytes actually read. Optional, pass `NULL`
* if you are not interested.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you
* are not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_read (tr_sys_file_t handle,
void * buffer,
uint64_t size,
uint64_t * bytes_read,
struct tr_error ** error);
/**
* @brief Like `pread ()`, except that the position is undefined afterwards.
* Not thread-safe.
*
* @param[in] handle Valid file descriptor.
* @param[out] buffer Buffer to store read data to.
* @param[in] size Number of bytes to read.
* @param[in] offset File offset in bytes to start reading from.
* @param[out] bytes_read Number of bytes actually read. Optional, pass `NULL`
* if you are not interested.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you
* are not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_read_at (tr_sys_file_t handle,
void * buffer,
uint64_t size,
uint64_t offset,
uint64_t * bytes_read,
struct tr_error ** error);
/**
* @brief Portability wrapper for `write ()`.
*
* @param[in] handle Valid file descriptor.
* @param[in] buffer Buffer to get data being written from.
* @param[in] size Number of bytes to write.
* @param[out] bytes_written Number of bytes actually written. Optional, pass
* `NULL` if you are not interested.
* @param[out] error Pointer to error object. Optional, pass `NULL` if
* you are not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_write (tr_sys_file_t handle,
const void * buffer,
uint64_t size,
uint64_t * bytes_written,
struct tr_error ** error);
/**
* @brief Like `pwrite ()`, except that the position is undefined afterwards.
* Not thread-safe.
*
* @param[in] handle Valid file descriptor.
* @param[in] buffer Buffer to get data being written from.
* @param[in] size Number of bytes to write.
* @param[in] offset File offset in bytes to start writing from.
* @param[out] bytes_written Number of bytes actually written. Optional, pass
* `NULL` if you are not interested.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you
* are not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_write_at (tr_sys_file_t handle,
const void * buffer,
uint64_t size,
uint64_t offset,
uint64_t * bytes_written,
struct tr_error ** error);
/**
* @brief Portability wrapper for `fsync ()`.
*
* @param[in] handle Valid file descriptor.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_flush (tr_sys_file_t handle,
struct tr_error ** error);
/**
* @brief Portability wrapper for `ftruncate ()`.
*
* @param[in] handle Valid file descriptor.
* @param[in] size Number of bytes to truncate (or extend) file to.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_truncate (tr_sys_file_t handle,
uint64_t size,
struct tr_error ** error);
/**
* @brief Tell system to prefetch some part of file which is to be read soon.
*
* @param[in] handle Valid file descriptor.
* @param[in] offset Offset in file to prefetch from.
* @param[in] size Number of bytes to prefetch.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_prefetch (tr_sys_file_t handle,
uint64_t offset,
uint64_t size,
struct tr_error ** error);
/**
* @brief Preallocate file to specified size in full or sparse mode.
*
* @param[in] handle Valid file descriptor.
* @param[in] size Number of bytes to preallocate file to.
* @param[in] flags Combination of @ref tr_sys_file_preallocate_flags_t values.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_preallocate (tr_sys_file_t handle,
uint64_t size,
int flags,
struct tr_error ** error);
/**
* @brief Portability wrapper for `mmap ()` for files.
*
* @param[in] handle Valid file descriptor.
* @param[in] offset Offset in file to map from.
* @param[in] size Number of bytes to map.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return Pointer to mapped file data on success, `NULL` otherwise (with
* `error` set accordingly).
*/
void * tr_sys_file_map_for_reading (tr_sys_file_t handle,
uint64_t offset,
uint64_t size,
struct tr_error ** error);
/**
* @brief Portability wrapper for `munmap ()` for files.
*
* @param[in] address Pointer to mapped file data.
* @param[in] size Size of mapped data in bytes.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_unmap (const void * address,
uint64_t size,
struct tr_error ** error);
/* File-related wrappers (utility) */
/**
* @brief Portability wrapper for `fgets ()`, removing EOL internally.
*
* Special care should be taken when reading from one of standard input streams
* (@ref tr_std_sys_file_t) since no UTF-8 conversion is currently being made.
*
* Reading from other streams (files, pipes) also leaves data untouched, so it
* should already be in UTF-8 encoding, or whichever else you expect.
*
* @param[in] handle Valid file descriptor.
* @param[out] buffer Buffer to store read zero-terminated string to.
* @param[in] buffer_size Buffer size in bytes, taking '\0' character into
* account.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you
* are not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
* Note that `false` will also be returned in case of end of file; if
* you need to distinguish the two, check if `error` is `NULL`
* afterwards.
*/
bool tr_sys_file_read_line (tr_sys_file_t handle,
char * buffer,
size_t buffer_size,
struct tr_error ** error);
/**
* @brief Portability wrapper for `fputs ()`, appending EOL internally.
*
* Special care should be taken when writing to one of standard output streams
* (@ref tr_std_sys_file_t) since no UTF-8 conversion is currently being made.
*
* Writing to other streams (files, pipes) also leaves data untouched, so it
* should already be in UTF-8 encoding, or whichever else you expect.
*
* @param[in] handle Valid file descriptor.
* @param[in] buffer Zero-terminated string to write.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_write_line (tr_sys_file_t handle,
const char * buffer,
struct tr_error ** error);
/**
* @brief Portability wrapper for `fprintf ()`.
*
* Special care should be taken when writing to one of standard output streams
* (@ref tr_std_sys_file_t) since no UTF-8 conversion is currently being made.
*
* Writing to other streams (files, pipes) also leaves data untouched, so it
* should already be in UTF-8 encoding, or whichever else you expect.
*
* @param[in] handle Valid file descriptor.
* @param[in] format String format to write.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
* @param[in] ... Format arguments.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_file_write_fmt (tr_sys_file_t handle,
const char * format,
struct tr_error ** error,
...);
/* Directory-related wrappers */
/**
* @brief Portability wrapper for `getcwd ()`.
*
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return Pointer to newly allocated buffer containing path to current
* directory (use @ref tr_free to free it when no longer needed) on
* success, `NULL` otherwise (with `error` set accordingly).
*/
char * tr_sys_dir_get_current (struct tr_error ** error);
/**
* @brief Like `mkdir ()`, but makes parent directories if needed.
*
* @param[in] path Path to directory.
* @param[in] flags Combination of @ref tr_sys_dir_create_flags_t values.
* @param[in] permissions Permissions to create directory with. Not used on
Windows.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you
* are not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_dir_create (const char * path,
int flags,
int permissions,
struct tr_error ** error);
/**
* @brief Portability wrapper for `mkdtemp ()`.
*
* @param[in,out] path_template Template path to directory. Should end with at
* least six 'X' characters. Upon success, trailing
* 'X' characters are replaced with actual random
* characters used to form a unique path to
* temporary directory.
* @param[out] error Pointer to error object. Optional, pass `NULL`
* if you are not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_dir_create_temp (char * path_template,
struct tr_error ** error);
/**
* @brief Portability wrapper for `opendir ()`.
*
* @param[in] path Path to directory.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return Opened directory descriptor on success, `TR_BAD_SYS_DIR` otherwise
* (with `error` set accordingly).
*/
tr_sys_dir_t tr_sys_dir_open (const char * path,
struct tr_error ** error);
/**
* @brief Portability wrapper for `readdir ()`.
*
* @param[in] handle Valid directory descriptor.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return Pointer to next directory entry name (stored internally, DO NOT pass
* it to @ref tr_free) on success, `NULL` otherwise (with `error` set
* accordingly). Note that `NULL` will also be returned in case of end
* of directory; if you need to distinguish the two, check if `error`
* is `NULL` afterwards.
*/
const char * tr_sys_dir_read_name (tr_sys_dir_t handle,
struct tr_error ** error);
/**
* @brief Portability wrapper for `closedir ()`.
*
* @param[in] handle Valid directory descriptor.
* @param[out] error Pointer to error object. Optional, pass `NULL` if you are
* not interested in error details.
*
* @return `True` on success, `false` otherwise (with `error` set accordingly).
*/
bool tr_sys_dir_close (tr_sys_dir_t handle,
struct tr_error ** error);
/** @} */
/** @} */
#ifdef __cplusplus
}
#endif
#endif
Reference in a new issue View git blame Copy permalink