Undocumented features

[Guy Harris]

> Take for instance fseek(3S) in 4.1 (same thing or very similar in system III):
> 	....
> 	Rewind(stream) is equivalent to fseek(stream, 0L, 0).

> 	SEE ALSO
> 		lseek(2), fopen(3)

> 	DIAGNOSTICS
> 		Fseek returns -1 for improper seeks.

> System III documentation says that fseek returns non-zero for improper seeks,
> zero otherwise. The truth of the matter is: rewind will return negative on
> PROPER seeks. If you want to test your rewind status, use fseek(stream, 0L, 0).
> This difference hardly makes rewind "equivalent" to fseek(stream, 0L, 0).

The S5 documentation clears up this; it says "Rewind(stream) is equivalent...
except that no value is returned."  Better late than never, I guess (grumble,
grumble, grumble)...

By the way, while we're on the topic of undocumented features:

In the System III "TTY(4)" manual page, it mentions the TCXONC "ioctl";

	TCXONC	Start/stop control.  If "arg" is 0, suspend output;
		if 1, restart suspended output.

They don't tell you that if "arg" is 2, it suspends *input* (i.e., sends an
XOFF to the other side), and if "arg" is 3, it restarts suspended *input*
(i.e., sends an XON).  If they didn't document it because it didn't work,
fine, *except that the code is still there in System V* and it's pretty
simple - if it doesn't work, "IXOFF" mode (what was called "tandem" mode
in V7) probably doesn't work either.  And no, it's still not documented in
System V (quite aside from the fact that the tty driver isn't documented
*at all* in the S5 UNIX User's Manual - it's only documented in the
*Administrator's* Manual.  Obviously, nobody but a system administrator needs
to know the characteristics and device-dependent "ioctl"s for the various
devices attached to your machine, right?  No mere programmer should be allowed
to write a screen editor... The (second) reorganization of the UPM/UUM
in System V Release 2 doesn't correct this botch - there's now a User's Manual
(mainly section 1), a Programmer's Manual (mainly sections 2 and 3), and
an Administrator's Manual (the system maintenance stuff from the other manuals).
Unfortunately, section 7 (which used to be section 4) - devices - is *still*
in the Administrator's Manual.  Put it back in the Programmer's Manual, where
it belongs.  *NOW*.

	Guy Harris
	{seismo,ihnp4,allegra}!rlgvax!guy