[Discuss] SCP from STDIN: "-t" option undocumented?

[Jerry Feldman]

On 12/23/2011 11:35 AM, Joshua Judson Rosen wrote:
> Jerry Feldman <gaf at blu.org> writes:
>> On 12/22/2011 05:38 PM, Flaherty, Patrick wrote:
>>>> Having just now quickly RTFSC and done a few superficial experiments I
>>>> conclude that the -t option (mnemonic for "to"; there's also a secret "from"
>>>> flag -f) is not suitable for use by humans.  It tells scp that it's in "server"
>>>> mode and should expect to communicate with its counterpart using some
>>>> undocumented protocol that appears to mix commands and data in-band via
>>>> stdin.  That's not the droid you're looking for...
>>> Use it anyways, no one has ever accused you of being a human -=]
>> http://linux.die.net/man/1/rcp
> "In particular, -f does not mean that the user's Kerberos ticket should
>  be forwarded!"
>
> It can be a good idea to document `interfaces for internal use only',
> just to explicitly state what they *are not*--to counteract the
> eliza effect when some hapless user happens upon them by accident,
> lest the outcome be less than happy.
>
> Maybe a patch to the scp manpage would be accepted, with that rationale?
>
The issue IMHO, is the lack of documentation for the -t option. I feel
that every interface should be documented. As a programmer I am used to
APIs. Historically, my colleagues find hidden APIs, and use them for
either because they are there or because they might be more efficient. I
would prefer that an API be published and marked as depricated or soon
to change. How many programs have been written to use undocumented APIs
only to crash when the vendor changes the API without notice. For
instance, a vendor might put in a hidden feature so internal users could
take advantage. I know IBM used to do this with their hardware so that
external vendors' hardware would operate less efficiently. Windows had
hidden interfaces for use by internal programmers and partners. So, in
this specific case, the man page should be updated to document the -t
option, but also note that this is for internal use and is intended to
differentiate between server and client.

-- 
Jerry Feldman <gaf at blu.org>
Boston Linux and Unix
PGP key id:3BC1EB90 
PGP Key fingerprint: 49E2 C52A FC5A A31F 8D66  C0AF 7CEA 30FC 3BC1 EB90