Undocumented features

[Guy Harris]

> Guy Harris, commenting on another netter's discovery that a needed feature
> actually exists but is undocumented:
> >Yup.  Welcome to the wonderful world of UNIX; a treasure hunt each day.
> >The annoying thing is that some of the stuff are real treasures, but the
> >authors have seen fit to bury them deeply...

> But look things over carefully before you use them.  I remember chasing
> fopen(3) in V7 - I wanted to be able to open a file for both reading and
> writing, so I set out to add code to do this.  Turned out that the code was
> already there - in addition to the documented "r", "w", and "a" options,
> you could add "+" to get read/write, as in "w+".  However, it didn't
> work...so was it undocumented because whoever wrote it not only blew it but
> didn't document it, or (more likely) because it wasn't done at the time the
> system was shipped?  In any case, I had only myself to blame for using an
> undocumented feature.

Oh yes, there are definitely zingers like that.  One real prize is the
"substr", "length", etc. functions in the "expr" command.  I first found
them in V7, where "expr" was YACC-based.  Then I looked at the S3 version,
which had been rewritten not to use YACC, but the rewriter took care to
preserve all those undocumented (and useful) functions.  (Or maybe the
S3 version came first, from UNIX/TS 1.0 vintage perhaps, and the V7 version
came later.  Whatever.)  Then I looked at the S5 version; guess what had
disappeared!  I suspect the problem was that that feature made "substr", etc.
reserved words and that tripped up some shell files.  (Anybody know the
real reason they disappeared?  Some of them were quite useful...)

The V7 version of "[rwa]+" worked if the (documented) S3 version did, except
if your umask took away your own read or write permissions, because the V7
and S3 code was the same except for a fix in S3 for a bug where such a umask
would prevent stdio from reopening the file after creating it.  (They didn't
remember that using the USG (and 4.2BSD) "open" you can create a file and
have the resulting descriptor open for reading and writing (and about damn
time, too!) until S5.)  The 4.xBSD (and possibly 2.xBSD) versions would have
worked, too, except that there was a bug in "fseek" (fixed in 4.2) that
screwed you if you had a stream open for reading and writing.  (The fix
has been posted on several occasions.)

Of course, just because something is a documented feature doesn't guarantee
that it works either...

By the way, the "defined()" operator and the __LINE__ and __FILE__ pseudo-
macros in the BTL UNIX C preprocessor, which have been around since V7,
are now documented in System V so they're safe to use.

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