From be75246754069a9f5d8d85cdc1b5def6c22a58e8 Mon Sep 17 00:00:00 2001 From: Matthias Andree Date: Wed, 16 Nov 2005 02:58:56 +0000 Subject: Clarify run-control file parser in respect of backslash escape sequences (document differences from C programming language escapes) and quoted strings (they will contain embedded CR or LF if the quoted string extends across two or more lines). svn path=/trunk/; revision=4445 --- NEWS | 4 ++++ fetchmail.man | 26 ++++++++++++++++++++------ 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/NEWS b/NEWS index 4232c864..b3bb8dea 100644 --- a/NEWS +++ b/NEWS @@ -284,6 +284,10 @@ fetchmail 6.3.0 (not yet released officially): * Fix several memory leaks and bugs in the SMTP/LMTP retry logic where fetchmail confused UNIX and Internet domain sockets. Sunil Shetye. * Man page (BUGS): document that passwords are length limited. Matthias Andree +* Man page: Document that quoted strings that run across line boundaries + contain the control characters (CR or LF). Document explicitly the backslash + escape sequences and their differences from the escape sequences used in the + C programming language. Matthias Andree # INTERNAL CHANGES * Switched to automake. Matthias Andree. diff --git a/fetchmail.man b/fetchmail.man index f0bb2997..70e9c6ba 100644 --- a/fetchmail.man +++ b/fetchmail.man @@ -1318,14 +1318,28 @@ option statements in a free-format, token-oriented syntax. There are four kinds of tokens: grammar keywords, numbers (i.e. decimal digit sequences), unquoted strings, and quoted strings. A quoted string is bounded by double quotes and may contain -whitespace (and quoted digits are treated as a string). An unquoted -string is any whitespace-delimited token that is neither numeric, string -quoted nor contains the special characters ',', ';', ':', or '='. +whitespace (and quoted digits are treated as a string). Note that +quoted strings will also contain line feed characters if they run across +two or more lines - so be sure that your strings are not word-wrapped +unless you want the embedded CR or LF characters. +An unquoted string is any whitespace-delimited token that is neither +numeric, string quoted nor contains the special characters ',', ';', +':', or '='. .PP Any amount of whitespace separates tokens in server entries, but is -otherwise ignored. You may use standard C-style escapes (\en, \et, -\eb, octal, and hex) to embed non-printable characters or string -delimiters in strings. +otherwise ignored. You may use escapes (\en for LF, \et for HT, +\&\eb for BS, \er for CR, \e\fInnn\fP for decimal (where nnn cannot start +with a 0), \e0\fIooo\fP for octal, and \ex\fIhh\fP for hex) to embed +non-printable characters or string delimiters in strings. +.PP +.B Warning: +while these resemble C-style escape sequences, fetchmail only supports +these seven styles. C supports more escape sequences that consist of +backslash (\e) and a single character, but does not support decimal +codes and does not require the leading 0 in octal notation. Example: +fetchmail interprets \e233 the same as \exE9 (Latin small letter e +with acute), where C would interpret \e233 as octal 0233 = \ex9B (CSI, +control sequence introducer). .PP Each server entry consists of one of the keywords 'poll' or 'skip', followed by a server name, followed by server options, followed by any -- cgit v1.2.3