#ifndef FS_API_H
#define FS_API_H
struct stat;
struct fs;
struct fs_file;
struct fs_lock;
struct hash_method;
/* Metadata with this prefix shouldn't actually be sent to storage. */
/* fs_write*() may return a hex-encoded object ID after write is finished.
This can be later on used to optimize reads by setting it before reading
the file. */
/* Calling this before fs_write_stream_finish() allows renaming the filename.
This can be useful if you don't know the final filename before writing it
(e.g. filename contains the file size). */
/* Original path of the file. The path that's eventually visible to a fs
backend may be something different, e.g. object ID. This allows the backend
to still access the original path. */
enum fs_properties {
/* Iteration is possible */
/* Iteration always returns all of the files (instead of possibly
slightly out of date view) */
/* Backend uses directories, which aren't automatically deleted
when its children are deleted. */
/* fs_copy() will copy the metadata if fs_set_metadata() hasn't
been explicitly called. */
/* Backend support asynchronous file operations. */
/* Backend supports FS_ITER_FLAG_OBJECTIDS. */
/* fs_copy() is fast even when file's metadata is changed */
};
enum fs_open_mode {
/* Open only for reading, or fail with ENOENT if it doesn't exist */
/* Create a new file, fail with EEXIST if it already exists */
/* Create a new file with a new unique name. The generated name is a
128bit hex-encoded string. The fs_open()'s path parameter specifies
only the directory where the file is created to. */
/* Create or replace a file */
/* Append to existing file, fail with ENOENT if it doesn't exist */
};
enum fs_open_flags {
/* File is important and writing must call fsync() or have equivalent
behavior. */
/* Asynchronous writes: fs_write() will fail with EAGAIN if it needs to
be called again (the retries can use size=0). For streams
fs_write_stream_finish() may request retrying with 0.
Asynchronous reads: fs_read() will fail with EAGAIN if it's not
finished and fs_read_stream() returns a nonblocking stream. */
/* fs_read_stream() must return a seekable input stream */
/* Backend should handle this file's operations immediately without
any additional command queueing. The caller is assumed to be the one
doing any rate limiting if needed. This flag can only be used with
ASYNC flag, synchronous requests are never queued. */
};
enum fs_iter_flags {
/* Iterate only directories, not files */
/* Request asynchronous iteration. */
/* Instead of returning object names, return <objectid>/<object name>.
If this isn't supported, the <objectid> is returned empty. The
object IDs are always hex-encoded data. This flag can be used only
if FS_PROPERTY_OBJECTIDS is enabled. */
/* Explicitly disable all caching for this iteration (if anything
happens to be enabled). This should be used only in situations where
the iteration is used to fix something that is broken, e.g. doveadm
force-resync. */
};
enum fs_op {
};
struct fs_settings {
but may also be useful for other purposes if they exist (they
may be NULL). */
const char *username;
const char *session_id;
/* Dovecot instance's base_dir */
const char *base_dir;
/* Directory where temporary files can be created at any time
(e.g. /tmp or mail_temp_dir) */
const char *temp_dir;
/* SSL client settings. */
/* Automatically try to rmdir() directories up to this path when
deleting files. */
const char *root_path;
/* When creating temporary files, use this prefix
(to avoid conflicts with existing files). */
const char *temp_file_prefix;
/* If the backend needs to do DNS lookups, use this dns_client for
them. */
/* Parent event to use, unless overridden by
fs_file_init_with_event() */
/* Enable debugging */
bool debug;
/* Enable timing statistics */
bool enable_timing;
};
struct fs_stats {
/* Number of fs_prefetch() calls. Counted only if fs_read*() hasn't
already been called for the file (which would be pretty pointless
to do). */
unsigned int prefetch_count;
/* Number of fs_read*() calls. Counted only if fs_prefetch() hasn't
already been called for the file. */
unsigned int read_count;
/* Number of fs_lookup_metadata() calls. Counted only if neither
fs_read*() nor fs_prefetch() has been called for the file. */
unsigned int lookup_metadata_count;
/* Number of fs_stat() calls. Counted only if none of the above
has been called (because the stat result should be cached). */
unsigned int stat_count;
/* Number of fs_write*() calls. */
unsigned int write_count;
/* Number of fs_exists() calls, which actually went to the backend
instead of being handled by fs_stat() call due to fs_exists() not
being implemented. */
unsigned int exists_count;
/* Number of fs_delete() calls. */
unsigned int delete_count;
/* Number of fs_copy() calls. If backend doesn't implement copying
operation but falls back to regular read+write instead, this count
isn't increased but the read+write counters are. */
unsigned int copy_count;
/* Number of fs_rename() calls. */
unsigned int rename_count;
/* Number of fs_iter_init() calls. */
unsigned int iter_count;
/* Number of bytes written by fs_write*() calls. */
/* Cumulative sum of usecs spent on calls - set only if
fs_settings.enable_timing=TRUE */
};
struct fs_metadata {
const char *key;
const char *value;
};
const struct fs_settings *set,
/* helper for fs_init, accepts a filesystem string
that can come directly from config */
/* same as fs_unref() */
/* Returns the parent filesystem (if this is a wrapper fs) or NULL if
there's no parent. */
/* Returns the filesystem's driver name. */
/* Returns the root fs's driver name (bypassing all wrapper fses) */
const char *path, int mode_flags);
/* If the file has an input streams open, close them. */
/* Return properties supported by backend. */
/* Return file's all metadata. */
/* Wrapper to fs_get_metadata() to lookup a specific key. Returns 1 if value_r
is set, 0 if key wasn't found, -1 if error. */
const char **value_r);
/* Returns the path given to fs_open(). If file was opened with
FS_OPEN_MODE_CREATE_UNIQUE_128 and the write has already finished,
return the path including the generated filename. */
/* Returns the file's fs. */
/* Returns the file's event. */
/* Return the error message for the last failed operation. */
/* Convenience function for the above. Errors aren't preserved across files. */
/* Try to asynchronously prefetch file into memory. Returns TRUE if file is
already in memory (i.e. caller should handle this file before prefetching
more), FALSE if not. The length is a hint of how much the caller expects
to read, but it may be more or less (0=whole file). */
/* Returns >0 if something was read, -1 if error (errno is set). */
/* Returns a stream for reading from file. Multiple streams can be opened,
and caller must destroy the streams before closing the file. */
files you can call fs_write() only once, the file creation is finished by it.
CREATE can return EEXIST here, if the destination file was already created.
With APPEND mode each fs_write() atomically appends the given data to
file. */
/* Write to file via output stream. The stream will be destroyed by
fs_write_stream_finish/abort. The returned ostream is already corked and
it doesn't need to be uncorked. */
/* Finish writing via stream, calling also o_stream_flush() on the stream and
after this call, same as with fs_write(). Anything written to the stream
won't be visible earlier. Returns 1 if ok, 0 if async write isn't finished
yet (retry calling fs_write_stream_finish_async()), -1 if error */
/* Abort writing via stream. Anything written to the stream is discarded.
o_stream_ignore_last_errors() is called on the output stream so the caller
doesn't need to do it. This must not be called after
fs_write_stream_finish(), i.e. it can't be used to abort a pending async
write. */
void fs_write_stream_abort_error(struct fs_file *file, struct ostream **output, const char *error_fmt, ...) ATTR_FORMAT(3, 4);
/* Set a hash to the following write. The storage can then verify that the
input data matches the specified hash, or fail if it doesn't. Typically
implemented by Content-MD5 header. */
const void *digest);
May call the callback immediately. */
void *context);
It's an error to call this when there are no pending async operations. */
/* Switch the fs to the current ioloop. This can be used to do fs_wait_async()
among other IO work. Returns TRUE if there is actually some work that can
be waited on. */
/* Returns 1 if file exists, 0 if not, -1 if error occurred. */
/* Delete a file. Returns 0 if file was actually deleted by us, -1 if error. */
/* Returns 0 if ok, -1 if error occurred (e.g. errno=ENOENT).
All fs backends may not support all stat fields. */
/* Get number of links to the file. This is the same as using fs_stat()'s
st_nlinks field, except not all backends support returning it via fs_stat().
Returns 0 if ok, -1 if error occurred. */
/* Copy an object with possibly updated metadata. Destination parent
directories are created automatically. Returns 0 if ok, -1 if error
occurred. */
/* Try to finish asynchronous fs_copy(). Returns the same as fs_copy(). */
/* Atomically rename a file. Destination parent directories are created
automatically. Returns 0 if ok, -1 if error occurred. */
/* Exclusively lock a file. If file is already locked, wait for it for given
number of seconds (0 = fail immediately). Returns 1 if locked, 0 if wait
timed out, -1 if error. */
/* Iterate through all files or directories in the given directory.
Doesn't recurse to child directories. It's not an error to iterate a
nonexistent directory. */
struct fs_iter *
struct fs_iter *
/* Returns 0 if ok, -1 if iteration failed. */
/* Returns the next filename. */
/* For asynchronous iterations: Specify the callback that is called whenever
there's more data available for reading. */
void *context);
/* For asynchronous iterations: If fs_iter_next() returns NULL, use this
function to determine if you should wait for more data or finish up. */
/* Return the filesystem's fs_stats. Note that each wrapper filesystem keeps
track of its own fs_stats calls. You can use fs_get_parent() to get to the
filesystem whose stats you want to see. */
#endif