dovecot-2.2: lib-fs: Updated fs_write_stream_*() comments relate...

[dovecot at dovecot.org]

details:   http://hg.dovecot.org/dovecot-2.2/rev/83f1b9956788
changeset: 18760:83f1b9956788
user:      Timo Sirainen <tss at iki.fi>
date:      Fri May 29 18:22:17 2015 +0300
description:
lib-fs: Updated fs_write_stream_*() comments related to ostream corking and nfinish.

diffstat:

 src/lib-fs/fs-api.h |  10 +++++++---
 1 files changed, 7 insertions(+), 3 deletions(-)

diffs (26 lines):

diff -r 1a52baa9bf27 -r 83f1b9956788 src/lib-fs/fs-api.h
--- a/src/lib-fs/fs-api.h	Fri May 29 17:51:21 2015 +0300
+++ b/src/lib-fs/fs-api.h	Fri May 29 18:22:17 2015 +0300
@@ -231,15 +231,19 @@
 int fs_write(struct fs_file *file, const void *data, size_t size);
 
 /* Write to file via output stream. The stream will be destroyed by
-   fs_write_stream_finish/abort. */
+   fs_write_stream_finish/abort. The returned ostream is already corked and
+   it doesn't need to be uncorked. */
 struct ostream *fs_write_stream(struct fs_file *file);
-/* Finish writing via stream. The file will be created/replaced/appended only
+/* Finish writing via stream, calling also o_stream_nfinish() on the stream and
+   handling any pending errors. The file will be created/replaced/appended only
    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 */
 int fs_write_stream_finish(struct fs_file *file, struct ostream **output);
 int fs_write_stream_finish_async(struct fs_file *file);
-/* Abort writing via stream. Anything written to the stream is discarded. */
+/* 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. */
 void fs_write_stream_abort(struct fs_file *file, struct ostream **output);
 
 /* Set a hash to the following write. The storage can then verify that the