Proposed change to fmemopen documentation (& semantics?) (fwd)

[Robert Bernecky <bernecky at acm dot org>]

Andreas Jaeger suggested that this group is an appropriate
target for this message.

Thanks.
Bob

Robert Bernecky                  Snake Island Research Inc.
bernecky@acm.org                 18 Fifth Street, Ward's Island
+1 416 203 0854                  Toronto, Ontario M5J 2B9 Canada
http://www.snakeisland.com


---------- Forwarded message ----------
Date: Fri, 8 Jun 2001 12:44:16 -0400 (EDT)
From: Robert Bernecky <bernecky@acm.org>
To: bug-glibc-manual@gnu.org
Cc: Robert Bernecky <bernecky@acm.org>,
     "John Gilmore (Secure Pointers)" <secptr@toad.com>,
     Greg McGary <greg@mcgary.org>, Tom Browder <tbrowder@home.com>
Subject: Proposed change to fmemopen documentation (& semantics?)

I've been working on some minor cleanup to fmemopen (String Streams)
in glibc. The current documentation reads:

"If the opentype specifies append mode, then the
initial file position is set to the first null character in
the buffer. Otherwise the initial file position is at the
beginning of the buffer.

When a stream open for writing is flushed or closed, a null
character (zero byte) is written at the end of the buffer if it fits.
You should add an extra byte to the size argument to
account for this. Attempts to write more than size bytes to
the buffer result in an error."

a. Question: If opentype specifies append mode, but there is NO
   null character in the buffer, what should fmemopen do?
   I can see 3 options:

	1. signal SIGSEGV
	2. set the initial file position to "the beginning of the
           buffer".
        3. set the initial file position to the end of the buffer
           (i.e., (buffer + size - 1))

   I have a vague preference for (1), as it will bring attention
   to the fact that fmemopen really has no clue as to where to
   start appending. The other choices mask the problem.

b. Question: The second paragraph says "...if it fits."
   The last sentence there says "Attempts to write more than
   size bytes to the buffer results in an error." Now, if
   the null to be appended to the buffer doesn't fit, does
   that count as an error, or is the append of the null simply
   to be ignored? I don't really care (ISMOP), but it would
   be nice if the documentation was explicit about the semantics
   here.

I've got my hands in fmemopen at present, so I'm able to make
minor semantic changes to match proposed documentation if
we can promptly agree on those semantics. I'll supply updated docn
text to match, too.

Thanks.
Bob

Robert Bernecky                  Snake Island Research Inc.
bernecky@acm.org                 18 Fifth Street, Ward's Island
+1 416 203 0854                  Toronto, Ontario M5J 2B9 Canada
http://www.snakeisland.com