From 83487ded7d70180e92ec2a808e95078f3774f99e Mon Sep 17 00:00:00 2001 Message-Id: <83487ded7d70180e92ec2a808e95078f3774f99e.1714000155.git.mdw@distorted.org.uk> From: Mark Wooding Date: Wed, 31 Dec 2008 13:19:09 +0000 Subject: [PATCH] server/tripe-admin.5: Describe the quoting convention. Organization: Straylight/Edgeware From: Mark Wooding Even though the admin interface has handled quoted arguments on input, and became careful about quoting results in f43df81, the convention has never been documented. Fix this appalling lapse! --- server/tripe-admin.5.in | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/server/tripe-admin.5.in b/server/tripe-admin.5.in index c493d187..05023729 100644 --- a/server/tripe-admin.5.in +++ b/server/tripe-admin.5.in @@ -54,14 +54,28 @@ server response consists of a line of ASCII text terminated by a single linefeed character. No command may be longer than 255 characters. .SS "General structure" Each command or response line consists of a sequence of -whitespace-separated words. The number and nature of whitespace -characters separating two words in a client command is not significant; -the server always uses a single space character. The first word in a +whitespace-separated tokens. The number and nature of whitespace +characters separating two tokens in a client command is not significant; +the server always uses a single space character. The first token in a line is a .I keyword identifying the type of command or response contained. Keywords in client commands are not case-sensitive; the server always uses uppercase for its keywords. +.PP +In order to allow tokens to contain internal whitespace, a quoting +mechanism is provided. Whitespace within matched pairs of quotes \(en +either single +.RB ` ' ' +or double +.RB ` """" ' +\(en is considered to be internal. Any character (other than newline) +may be escaped by preceding it with a backslash +.RB ` \e ': +in particular, this can be used to include quote characters. It is +impossible for a token to contain a newline character. +.PP +On output, the server will use double quotes when necessary. .SS "Simple commands" For simple client command, the server responds with zero or more .B INFO @@ -231,9 +245,9 @@ will issue the corresponding .BR BG ... responses when appropriate.) .SS "Network addresses" -A network address is a sequence of words. The first is a token +A network address is a sequence of tokens. The first is a token identifying the network address family. The length of an address and -the meanings of the subsequent words depend on the address family. +the meanings of the subsequent tokens depend on the address family. Address family tokens are not case-sensitive on input; on output, they are always in upper-case. .PP @@ -248,7 +262,7 @@ does not block the main server, but will block the requesting client, unless the command is run in the background. .PP If, on input, no recognised address family token is found, the following -words are assumed to represent an +tokens are assumed to represent an .B INET address. Addresses output by the server always have an address family token. @@ -259,7 +273,7 @@ and .BR SERVINFO ) produce output in the form of .IB key = value -pairs, one per word. Neither the +pairs, one per token. Neither the .I key nor the .I value @@ -794,7 +808,7 @@ line is printed giving its name. .B "VERSION" Causes the server to emit an .B INFO -line stating its software version, as two words: the server name, and +line stating its software version, as two tokens: the server name, and its version string. The server name .B tripe is reserved to the Straylight/Edgeware implementation. @@ -860,9 +874,9 @@ understood. (For any command.) The command couldn't be understood: e.g., the number of arguments was wrong. .SP -.BI "bad-time-spec " word +.BI "bad-time-spec " token The -.I word +.I token is not a valid time interval specification. Acceptable time specifications are nonnegative integers followed optionally by .BR d , @@ -1259,7 +1273,7 @@ and discarded the valid one. An unknown key-exchange message arrived. .SS "PEER warnings" These are largely concerned with management of peers and the low-level -details of the network protocol. The second word is usually the name of +details of the network protocol. The second token is usually the name of a peer, or .RB ` \- ' if none is relevant. @@ -1377,7 +1391,7 @@ before. It may be an accidental duplication because the 'net is like that, or a deliberate attempt at a replay. .SS "TUN warnings" These concern the workings of the system-specific tunnel driver. The -second word is the name of the tunnel interface in question, or +second token is the name of the tunnel interface in question, or .RB ` \- ' if none. .SP -- [mdw]