- Remove underscores from the internal structure name, as it doesn't collide

  with the user's namespace.

- Correct size and position variables type from long to size_t.

- Do not set errno to ENOMEM on malloc failure, as malloc already does so.

- Implement the concept of "buffer data length", which mandates what SEEK_END
  refers to and the allowed extent for a read.

- Use NULL as read-callback if the buffer is opened in write-only mode.
  Conversely, use NULL as write-callback when opened in read-only mode.

- Implement the handling of the ``b'' character in the mode argument. A binary
  buffer differs from a text buffer (default mode if ``b'' is omitted) in that
  NULL bytes are never appended to writes and that the "buffer data length"
  equals to the size of the buffer.

- Remove shall from the man page. Use indicative instead. Also, specify that
  the ``b'' flag does not conform with POSIX but is supported by glibc.

- Update the regression test so that the ``b'' functionality and the "buffer
  data length" concepts are tested.

- Minor style(9) corrections.

Suggested by:	jilles
Reviewed by:	cognet
Approved by:	cognet

1 files changed, 14 insertions, 5 deletions

diff --git a/lib/libc/stdio/fopen.3 b/lib/libc/stdio/fopen.3
index 41d66b7..a07be38 100644
--- a/lib/libc/stdio/fopen.3
+++ b/lib/libc/stdio/fopen.3
@@ -118,7 +118,9 @@ after either the
 or the first letter.
 This is strictly for compatibility with
 .St -isoC
-and has no effect; the ``b'' is ignored.
+and has effect only for
+.Fn fmemopen
+; otherwise the ``b'' is ignored.
 .Pp
 Any created files will have mode
 .Do Dv S_IRUSR
@@ -216,7 +218,7 @@ and
 arguments with a stream.
 The
 .Fa buf
-argument shall be either a null pointer or point to a buffer that
+argument is either a null pointer or point to a buffer that
 is at least
 .Fa size
 bytes long.
@@ -224,10 +226,15 @@ If a null pointer is specified as the
 .Fa buf
 argument,
 .Fn fmemopen
-shall allocate
+allocates
 .Fa size
-bytes of memory. This buffer shall be automatically freed when the
-stream is closed.
+bytes of memory. This buffer is automatically freed when the
+stream is closed. Buffers can be opened in text-mode (default) or binary-mode
+(if ``b'' is present in the second or third position of the
+.Fa mode
+argument). Buffers opened in text-mode make sure that writes are terminated with
+a NULL byte, if the last write hasn't filled up the whole buffer. Buffers
+opened in binary-mode never append a NULL byte.
 .Sh RETURN VALUES
 Upon successful completion
 .Fn fopen ,
@@ -327,3 +334,5 @@ The
 function
 conforms to 
 .St -p1003.1-2008 .
+The ``b'' mode does not conform to any standard
+but is also supported by glibc.