fs-api.h revision 1c31ad9a2e071bd8ac9b98ad8070209ff85f1351
8804300e6c170eea0cab8e570bf5ebd3b2895c0aTimo Sirainen /* Iteration is possible */
8804300e6c170eea0cab8e570bf5ebd3b2895c0aTimo Sirainen /* Iteration always returns all of the files (instead of possibly
8804300e6c170eea0cab8e570bf5ebd3b2895c0aTimo Sirainen slightly out of date view) */
e298b836845e07c9c95b4f068244f6c24252687eTimo Sirainen /* Backend uses directories, which aren't automatically deleted
e298b836845e07c9c95b4f068244f6c24252687eTimo Sirainen when its children are deleted. */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen /* Open only for reading, or fail with ENOENT if it doesn't exist */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen /* Create a new file, fail with EEXIST if it already exists */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen /* Create a new file with a new unique name. The generated name is a
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen 128bit hex-encoded string. The fs_open()'s path parameter specifies
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen only the directory where the file is created to. */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen /* Create or replace a file */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen /* Append to existing file, fail with ENOENT if it doesn't exist */
d11111fc5356108b6408a58b4ff1811d5b5678edTimo Sirainen /* File is important and writing must call fsync() or have equivalent
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen /* Asynchronous writes: fs_write() will fail with EAGAIN if it needs to
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen be called again (the retries can use size=0). For streams
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen fs_write_stream_finish() may request retrying with 0.
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen Asynchronous reads: fs_read() will fail with EAGAIN if it's not
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen finished and fs_read_stream() returns a nonblocking stream. */
a06af8e117e14e2ddc5835bcbe0d2f0370cbc0a1Timo Sirainen /* fs_read_stream() must return a seekable input stream */
63e94e8f57920b510fcdc479c5482ba9f4337a5cTimo Sirainen /* Iterate only directories, not files */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen /* Dovecot instance's base_dir */
1680fed5026a52fa4f47eb4cc6d82ec8dddcc50bTimo Sirainen /* Directory where temporary files can be created at any time
1680fed5026a52fa4f47eb4cc6d82ec8dddcc50bTimo Sirainen (e.g. /tmp or mail_temp_dir) */
c4a629cd7110285f0046793e4d0b29dee327dfbfTimo Sirainen /* SSL client settings. */
c4a629cd7110285f0046793e4d0b29dee327dfbfTimo Sirainen const struct ssl_iostream_settings *ssl_client_set;
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen /* Automatically try to rmdir() directories up to this path when
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen deleting files. */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen /* When creating temporary files, use this prefix
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen (to avoid conflicts with existing files). */
1c31ad9a2e071bd8ac9b98ad8070209ff85f1351Timo Sirainen /* Enable debugging */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen const char *key;
c59b9c273b41f7bcf51f6803110b67813879ff05Timo SirainenARRAY_DEFINE_TYPE(fs_metadata, struct fs_metadata);
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainentypedef void fs_file_async_callback_t(void *context);
d4c3d55021bcbf2b062f4782b1cde9115d35aefcTimo Sirainenint fs_init(const char *driver, const char *args,
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainenstruct fs_file *fs_file_init(struct fs *fs, const char *path, int mode_flags);
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Return properties supported by backend. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainenenum fs_properties fs_get_properties(struct fs *fs);
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Add/replace metadata when saving a file. This makes sense only when the
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen file is being created/replaced. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainenvoid fs_set_metadata(struct fs_file *file, const char *key, const char *value);
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Return file's all metadata. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Returns the path given to fs_open(). If file was opened with
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen FS_OPEN_MODE_CREATE_UNIQUE_128 and the write has already finished,
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen return the path including the generated filename. */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainenconst char *fs_file_path(struct fs_file *file);
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen/* Return the error message for the last failed operation. */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen/* Convenience function for the above. Errors aren't preserved across files. */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainenconst char *fs_file_last_error(struct fs_file *file);
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Try to asynchronously prefetch file into memory. Returns TRUE if file is
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen already in memory (i.e. caller should handle this file before prefetching
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen more), FALSE if not. The length is a hint of how much the caller expects
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen to read, but it may be more or less (0=whole file). */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainenbool fs_prefetch(struct fs_file *file, uoff_t length);
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen/* Returns >0 if something was read, -1 if error (errno is set). */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainenssize_t fs_read(struct fs_file *file, void *buf, size_t size);
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen/* Returns a stream for reading from file. Multiple streams can be opened,
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen and caller must destroy the streams before closing the file. */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainenstruct istream *fs_read_stream(struct fs_file *file, size_t max_buffer_size);
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen/* Returns 0 if ok, -1 if error (errno is set). Note: With CREATE/REPLACE mode
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen files you can call fs_write() only once, the file creation is finished by it.
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen CREATE can return EEXIST here, if the destination file was already created.
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen With APPEND mode each fs_write() atomically appends the given data to
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainenint fs_write(struct fs_file *file, const void *data, size_t size);
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen/* Write to file via output stream. The stream will be destroyed by
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainenstruct ostream *fs_write_stream(struct fs_file *file);
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen/* Finish writing via stream. The file will be created/replaced/appended only
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen after this call, same as with fs_write(). Anything written to the stream
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen won't be visible earlier. Returns 1 if ok, 0 if async write isn't finished
ba886767d3817d210b20e1d42983078d189fb13cTimo Sirainen yet (retry calling fs_write_stream_finish_async()), -1 if error */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainenint fs_write_stream_finish(struct fs_file *file, struct ostream **output);
ba886767d3817d210b20e1d42983078d189fb13cTimo Sirainenint fs_write_stream_finish_async(struct fs_file *file);
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen/* Abort writing via stream. Anything written to the stream is discarded. */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainenvoid fs_write_stream_abort(struct fs_file *file, struct ostream **output);
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Call the specified callback whenever the file can be read/written to.
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen May call the callback immediately. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainenvoid fs_file_set_async_callback(struct fs_file *file,
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Wait until some file can be read/written to more before returning.
2766f1de8141c09767a959d2d2c3065c5a300bf0Timo Sirainen It's an error to call this when there are no pending async operations.
2766f1de8141c09767a959d2d2c3065c5a300bf0Timo Sirainen Returns 0 if ok, -1 if timed out. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Returns 1 if file exists, 0 if not, -1 if error occurred. */
42d2fdfbe4047c0aab78c76a10f31766aa53ecd7Timo Sirainen/* Delete a file. Returns 0 if file was actually deleted by us, -1 if error. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Returns 0 if ok, -1 if error occurred (e.g. errno=ENOENT).
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen All fs backends may not support all stat fields. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainenint fs_stat(struct fs_file *file, struct stat *st_r);
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Copy an object with possibly updated metadata. Destination parent
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen directories are created automatically. Returns 0 if ok, -1 if error
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainenint fs_copy(struct fs_file *src, struct fs_file *dest);
8bfb2ecbe654afe6893052959c42b4851119e76dTimo Sirainen/* Try to finish asynchronous fs_copy(). Returns the same as fs_copy(). */
ba886767d3817d210b20e1d42983078d189fb13cTimo Sirainenint fs_copy_finish_async(struct fs_file *dest);
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Atomically rename a file. Destination parent directories are created
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen automatically. Returns 0 if ok, -1 if error occurred. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainenint fs_rename(struct fs_file *src, struct fs_file *dest);
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen/* Exclusively lock a file. If file is already locked, wait for it for given
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen number of seconds (0 = fail immediately). Returns 1 if locked, 0 if wait
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainen timed out, -1 if error. */
c33d3f93abf8392fdc60e12bea41ffd12cc85a8dTimo Sirainenint fs_lock(struct fs_file *file, unsigned int secs, struct fs_lock **lock_r);
63e94e8f57920b510fcdc479c5482ba9f4337a5cTimo Sirainen/* Iterate through all files or directories in the given directory.
a58b73c69e2d608843406b5809063d038ae67699Timo Sirainen Doesn't recurse to child directories. It's not an error to iterate a
a58b73c69e2d608843406b5809063d038ae67699Timo Sirainen nonexistent directory. */
63e94e8f57920b510fcdc479c5482ba9f4337a5cTimo Sirainenfs_iter_init(struct fs *fs, const char *path, enum fs_iter_flags flags);
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Returns 0 if ok, -1 if iteration failed. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Returns the next filename. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainenconst char *fs_iter_next(struct fs_iter *iter);