This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: BZ#10254: Explain additional fopen parameters


On 04/09/2012 06:47 PM, Roland McGrath wrote:
+@Theglibc{} defines additional character fors use in @var{opentype}:

characters for


+@item c
+The file is opened with cancellation in the I/O functions disabled.

xref here?

The whole pthread library is undocumented, I haven't found a place for xref.


+@item e
+The file is opened with the flag @code{O_CLOEXEC}, thus it is closed
+if you use any of the @code{exec@dots{}} functions (@pxref{Executing a
+File}).

Unfortunately the manual does not yet describe O_CLOEXEC. So this is incongruous. I think it's best here to just describe the behavior:

The underlying file descriptor will be closed if you use any of the
@code{exec@dots{}} functions (@pxref{Executing a File}).  (This is
equivalent to having set @code{FD_CLOEXEC} on that descriptor.
@xref{Descriptor Flags}.)

Thanks.
+@item m
+The file is opened and accessed using @code{mmap}. This is only
+supported with files opened for reading.

Two spaces after a sentence.


+@item x
+Insist on creating a new file---if a file @var{filename} already
+exists, @code{fopen} fails rather than opening it.  If you use
+@samp{x} you are guaranteed that you will not clobber an existing
+file.  This is equivalent to the @code{O_EXCL} option to the
+@code{open} function (@pxref{Opening and Closing Files})

Missing period.


+The @samp{x} modifier is part of @w{ISO C 11}.

I don't think we have a precedent yet for citing this standard. The analog for C99 looks like @w{ISO C99}.


Thanks, Roland

I've added all your changes and also fixed a typo that Hakon Hallingstad found.


Ok to commit the updated patch?

Andreas
2012-04-09  Andreas Jaeger  <aj@suse.de>

	[BZ #10254]
	* manual/stdio.texi (Opening Streams): Document additional fopen
	parameters.


diff --git a/manual/stdio.texi b/manual/stdio.texi
index 0d23daa..e870afb 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -196,13 +196,31 @@ Additional characters may appear after these to specify flags for the
call. Always put the mode (@samp{r}, @samp{w+}, etc.) first; that is
the only part you are guaranteed will be understood by all systems.


-@Theglibc{} defines one additional character for use in
-@var{opentype}: the character @samp{x} insists on creating a new
-file---if a file @var{filename} already exists, @code{fopen} fails
-rather than opening it.  If you use @samp{x} you are guaranteed that
-you will not clobber an existing file.  This is equivalent to the
-@code{O_EXCL} option to the @code{open} function (@pxref{Opening and
-Closing Files}).
+@Theglibc{} defines additional characters for use in @var{opentype}:
+
+@table @samp
+@item c
+The file is opened with cancellation in the I/O functions disabled.
+
+@item e
+The underlying file descriptor will be closed if you use any of the
+@code{exec@dots{}} functions (@pxref{Executing a File}).  (This is
+equivalent to having set @code{FD_CLOEXEC} on that descriptor.
+@xref{Descriptor Flags}.)
+
+@item m
+The file is opened and accessed using @code{mmap}.  This is only
+supported with files opened for reading.
+
+@item x
+Insist on creating a new file---if a file @var{filename} already
+exists, @code{fopen} fails rather than opening it.  If you use
+@samp{x} you are guaranteed that you will not clobber an existing
+file.  This is equivalent to the @code{O_EXCL} option to the
+@code{open} function (@pxref{Opening and Closing Files}).
+
+The @samp{x} modifier is part of @w{ISO C11}.
+@end table

 The character @samp{b} in @var{opentype} has a standard meaning; it
 requests a binary stream rather than a text stream.  But this makes no

--
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]