fs-api.h revision 8804300e6c170eea0cab8e570bf5ebd3b2895c0a
8804300e6c170eea0cab8e570bf5ebd3b2895c0aTimo Sirainen /* Iteration is possible */
8804300e6c170eea0cab8e570bf5ebd3b2895c0aTimo Sirainen /* Iteration always returns all of the files (instead of possibly
8804300e6c170eea0cab8e570bf5ebd3b2895c0aTimo Sirainen slightly out of date view) */
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 */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen /* File being written isn't very important, performance is more
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen important than actually guaranteeing that the file gets saved */
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. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen /* Dovecot instance's base_dir */
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). */
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. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Delete a file. Returns 1 if file was actually deleted by us,
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen 0 if file didn't exist, -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);
ba886767d3817d210b20e1d42983078d189fb13cTimo Sirainen/* Try to finish asynchronous 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);
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainen/* Iterate through all files (but not 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. */
c59b9c273b41f7bcf51f6803110b67813879ff05Timo Sirainenstruct fs_iter *fs_iter_init(struct fs *fs, const char *path);
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);