[PATCH] open.2: add some comments on O_SYNC and friends

[PATCH] open.2: add some comments on O_SYNC and friends

[Christoph Hellwig]

The language probably needs some editing, but this was the best
I could come up with.


Signed-off-by: Christoph Hellwig <hch-jcswGhMUV9g@public.gmane.org>

Index: man-pages/man2/open.2
===================================================================
--- man-pages.orig/man2/open.2	2009-08-27 14:43:43.589383500 -0300
+++ man-pages/man2/open.2	2009-08-27 14:51:01.729354515 -0300
@@ -276,12 +276,12 @@ The following symbolic constants are pro
 Try to minimize cache effects of the I/O to and from this file.
 In general this will degrade performance, but it is useful in
 special situations, such as when applications do their own caching.
-File I/O is done directly to/from user space buffers.
-The I/O is synchronous, that is, at the completion of a
-.BR read (2)
-or
-.BR write (2),
-data is guaranteed to have been transferred.
+File I/O is done directly to/from user space buffers.  The
+\fBO_DIRECT\fP flag alone does make at an effort to transfer
+data synchronously, but does not give the guarantees of the
+\fBO_SYNC\fP that data and nessecary data must be transferred.
+To guarantee synchronous I/O the \fBO_SYNC\fP must be used
+in addition to \fBO_DIRECT\fP.
 See
 .B NOTES
 below for further discussion.
@@ -661,8 +661,14 @@ amongst others
 
 POSIX provides for three different variants of synchronized I/O,
 corresponding to the flags \fBO_SYNC\fP, \fBO_DSYNC\fP and
-\fBO_RSYNC\fP.
-Currently (2.1.130) these are all synonymous under Linux.
+\fBO_RSYNC\fP.  Currently (2.6.31) Linux only implements the
+\fBO_SYNC\fP but glibc maps \fBO_DSYNC\fP and \fBO_SYNC\fP to
+the same numerical value.  Most Linux filesystems do however not
+actually implement the Posix \fBO_SYNC\fP, semantics which
+require all metadata updates of a write to be on disk on returning
+to userspace, but only the \fBO_DSYNC\fP semantics, which require
+only actual file data and metadata nessecary to retreive it to
+be on disk by the time the system call returns.
 
 Note that
 .BR open ()
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open.2: add some comments on O_SYNC and friends

[Michael Kerrisk]

Hi Christoph,

Thanks for the patch. A few comments below.

On Thu, Aug 27, 2009 at 8:00 PM, Christoph Hellwig <hch-jcswGhMUV9g@public.gmane.org> wrote:
> The language probably needs some editing, but this was the best
> I could come up with.
>
>
> Signed-off-by: Christoph Hellwig <hch-jcswGhMUV9g@public.gmane.org>
>
> Index: man-pages/man2/open.2
> ===================================================================
> --- man-pages.orig/man2/open.2  2009-08-27 14:43:43.589383500 -0300
> +++ man-pages/man2/open.2       2009-08-27 14:51:01.729354515 -0300
> @@ -276,12 +276,12 @@ The following symbolic constants are pro
>  Try to minimize cache effects of the I/O to and from this file.
>  In general this will degrade performance, but it is useful in
>  special situations, such as when applications do their own caching.
> -File I/O is done directly to/from user space buffers.
> -The I/O is synchronous, that is, at the completion of a
> -.BR read (2)
> -or
> -.BR write (2),
> -data is guaranteed to have been transferred.
> +File I/O is done directly to/from user space buffers.  The
> +\fBO_DIRECT\fP flag alone does make at an effort to transfer
> +data synchronously, but does not give the guarantees of the
> +\fBO_SYNC\fP that data and nessecary data must be transferred.

Here I wrote "data and necessary metadata".
Okay?

> +To guarantee synchronous I/O the \fBO_SYNC\fP must be used
> +in addition to \fBO_DIRECT\fP.
>  See
>  .B NOTES
>  below for further discussion.
> @@ -661,8 +661,14 @@ amongst others
>
>  POSIX provides for three different variants of synchronized I/O,
>  corresponding to the flags \fBO_SYNC\fP, \fBO_DSYNC\fP and
> -\fBO_RSYNC\fP.
> -Currently (2.1.130) these are all synonymous under Linux.
> +\fBO_RSYNC\fP.  Currently (2.6.31) Linux only implements the
> +\fBO_SYNC\fP but glibc maps \fBO_DSYNC\fP and \fBO_SYNC\fP to
> +the same numerical value.

Here, I made it

    but glibc maps O_DSYNC and O_RSYNC to
    the same numerical value as O_SYNC.

Okay?

> +the same numerical value
> Most Linux filesystems do however not
> +actually implement the Posix \fBO_SYNC\fP, semantics which
> +require all metadata updates of a write to be on disk on returning
> +to userspace, but only the \fBO_DSYNC\fP semantics, which require
> +only actual file data and metadata nessecary to retreive it to
> +be on disk by the time the system call returns.
>
>  Note that
>  .BR open ()

Aside from the changes notes above, and some language clean-ups, I
applied your patch as given, for man-pages-3.23.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Watch my Linux system programming book progress to publication!
http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] open.2: add some comments on O_SYNC and friends

[Christoph Hellwig]

On Sun, Sep 20, 2009 at 07:41:34AM +0200, Michael Kerrisk wrote:
> > -data is guaranteed to have been transferred.
> > +File I/O is done directly to/from user space buffers. ?The
> > +\fBO_DIRECT\fP flag alone does make at an effort to transfer
> > +data synchronously, but does not give the guarantees of the
> > +\fBO_SYNC\fP that data and nessecary data must be transferred.
> 
> Here I wrote "data and necessary metadata".
> Okay?

Yes.

> > ?POSIX provides for three different variants of synchronized I/O,
> > ?corresponding to the flags \fBO_SYNC\fP, \fBO_DSYNC\fP and
> > -\fBO_RSYNC\fP.
> > -Currently (2.1.130) these are all synonymous under Linux.
> > +\fBO_RSYNC\fP. ?Currently (2.6.31) Linux only implements the
> > +\fBO_SYNC\fP but glibc maps \fBO_DSYNC\fP and \fBO_SYNC\fP to
> > +the same numerical value.
> 
> Here, I made it
> 
>     but glibc maps O_DSYNC and O_RSYNC to
>     the same numerical value as O_SYNC.
> 
> Okay?

Yes, again much better than my version.

> Aside from the changes notes above, and some language clean-ups, I
> applied your patch as given, for man-pages-3.23.

Thanks a lot.  Note that in the meantime I sent patches to implement
real O_SYNC/O_DSYNC and I'll send you another update once they get
applied.

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html