open.2: add some comments on O_SYNC and friends

PATCH In review Christoph Hellwig 2 participants 3 messages Aug 27, 2009 – Sep 22, 2009 2 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore

Share & tools

lore

Christoph Hellwig

author

2009-08-27 18:00 UTC #0 lore raw

PATCH 1/1 open.2: add some comments on O_SYNC and friends

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

Signed-off-by Christoph Hellwig <[email protected]>

man2/open.2 +14 -8

Index: man-pages/man2/open.2
===================================================================
@@ -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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): [email protected]

Michael Kerrisk

2009-09-20 05:41 UTC #2 lore raw

Hi Christoph,

Thanks for the patch. A few comments below.

Quoted 14 lines · Christoph Hellwig

The language probably needs some editing, but this was the best I could come up with.
Signed-off-by Christoph Hellwig <[email protected]>
Index: man-pages/man2/open.2
===================================================================
man2/open.2 2009-08-27 14:51:01.729354515 -0300 renamed from man2/open.2 2009-08-27 14:43:43.589383500 -0300 +0 -0
@@ -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.

man2/open.2 2009-08-27 14:51:01.729354515 -0300

Quoted 10 lines

man2/open.2 2009-08-27 14:51:01.729354515 -0300 renamed from man2/open.2 2009-08-27 14:43:43.589383500 -0300 +4 -6

-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?

Quoted 10 lines

man2/open.2 2009-08-27 14:51:01.729354515 -0300 renamed from man2/open.2 2009-08-27 14:43:43.589383500 -0300 +2 -0
+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.
man2/open.2 2009-08-27 14:51:01.729354515 -0300 renamed from man2/open.2 2009-08-27 14:43:43.589383500 -0300 +0 -0
@@ -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.

man2/open.2 2009-08-27 14:51:01.729354515 -0300

Quoted 4 lines

man2/open.2 2009-08-27 14:51:01.729354515 -0300 renamed from man2/open.2 2009-08-27 14:43:43.589383500 -0300 +3 -1
-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?

Quoted 10 lines

+the same numerical value
Most Linux filesystems do however not
man2/open.2 2009-08-27 14:51:01.729354515 -0300 renamed from man2/open.2 2009-08-27 14:43:43.589383500 -0300 +5 -0
+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

Signature · 8 lines

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 [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

A message that is not in the archive (sent off-list or not yet received): cfd18e0f0909192241y5b45aa79u305f1e8e3295aea9-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org

Christoph Hellwig

author

2009-09-22 11:42 UTC #4 lore raw

Quoted 8 lines · Michael Kerrisk

man2/open.2 The following symbolic constants are pro · line 282
Quoted 5 lines
man2/open.2 +4 -1
-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.

Quoted 10 lines

man2/open.2 amongst others
Quoted 7 lines
?POSIX provides for three different variants of synchronized I/O, ?corresponding to the flags \fBO_SYNC\fP, \fBO_DSYNC\fP and -\fBO_RSYNC\fP.
man2/open.2 +3 -1
-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

Quoted 4 lines

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

Yes, again much better than my version.

Quoted 2 lines

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 [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html