/usr/share/cone/smapsyntax.html is in cone 0.89-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 | <html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>
<title>SMAP syntax overview</title>
<link rel="stylesheet" href="manpage.css" type="text/css"/>
<link rel="home" href="index.html" title="Cone: COnsole Newsreader And Emailer"/>
<link rel="up" href="smap1.html" title="Appendix A. Simple Mail Access Protocol, Version 1"/>
<link rel="prev" href="smap1.html" title="Appendix A. Simple Mail Access Protocol, Version 1"/>
<link rel="next" href="conn.html" title="SMAP connection negotiation"/>
<link xmlns="" rel="icon" href="icon.gif" type="image/gif"/>
<meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/>
<!--
Copyright 2002 - 2007 Double Precision, Inc. See COPYING for distribution
information.
-->
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center" rowspan="1">SMAP syntax
overview</th>
</tr>
<tr>
<td width="20%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="smap1.html" shape="rect">Prev</a> </td>
<th width="60%" align="center" rowspan="1" colspan="1">
Appendix A. Simple Mail Access Protocol, Version
1</th>
<td width="20%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="conn.html" shape="rect">Next</a></td>
</tr>
</table>
<hr/>
</div>
<div class="section" title="SMAP syntax overview">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="smapsyntax" shape="rect" name="smapsyntax"> </a>SMAP syntax overview</h3>
</div>
</div>
</div>
<p>The rest of this document defines the actual SMAP commands,
but all commands from the client, and replies from the server,
follow the same basic syntax. All SMAP commands, and replies,
use the UTF-8 character set (no matter what the natural
language is used for error messages, or prompts). An SMAP
command is generally one or more words. The words are separated
by at least one whitespace character (U+0020, U+0009, or
U+000D). An SMAP command is terminated by the newline
character, (U+000A).</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The server does not translate actual message contents to
UTF-8. The server provides the contents of a message as is,
to the client. The UTF-8 character set is used for:</p>
<div class="itemizedlist">
<ul class="itemizedlist" type="disc">
<li class="listitem">
<p>Names of folders</p>
</li>
<li class="listitem">
<p>Error and status messages</p>
</li>
<li class="listitem">
<p>Search strings</p>
</li>
</ul>
</div>
<p>Other text-based entities already use an implicit
character set (such as US-ASCII for names of E-mail headers)
or are specified as opaque text strings (such as message
unique identifiers, loginid and password) and have no
explicitly defined character set.</p>
</div>
<div class="section" title="Maximum limitations and timeouts">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="smaplimits" shape="rect" name="smaplimits"> </a>Maximum limitations and timeouts</h4>
</div>
</div>
</div>
<p><a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2822.txt" target="_top" shape="rect">RFC 2822</a> sets the maximum length of a line
in an E-mail message as 998 characters. This limitation is
applicable to SMAP, since SMAP deals with E-mail.
Additionally, SMAP commands may not exceed 8000 characters.
SMAP servers should accept commands up to 8000 characters
long. SMAP clients should not send commands that exceed 8000
characters in length.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>This, of course, does not apply to binary-formatted
multiline replies, that transfer binary MIME
attachments.</p>
</div>
<p>SMAP servers should terminate inactive SMAP clients. SMAP
servers must have a timeout of at least 30 minutes. SMAP
clients must not wait more than 29 minutes before sending the
next command to the server. SMAP clients that must remain
idle for a prolonged period of time should periodically send
the <code class="literal">NOOP</code> command to prevent
themselves from being disconnected for inactivity.</p>
</div>
<div class="section" title="Words">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id696426" shape="rect" name="id696426"> </a>Words</h4>
</div>
</div>
</div>
<p>A word can contain any character except for a control
character (U+0000 through U+001F). If a word contains spaces
or quotes (U+0020 or U+0022), a quote must be added before
the first character of the word, and a second quote character
must follow the last character of the word. Quotes that are
part of the word are doubled. For example: <code class="literal">"Learning the ""ABC""'s"</code> is a single SMAP
word. The word contains a single quote character before the
letter "A" and a second quote character after the letter "C".
Everything else is as it appears. A word that contains a
single quote character is represented as <code class="literal">""""</code>. A word that's meant to be completely
empty is represented by two quotes: <code class="literal">""</code>.</p>
</div>
<div class="section" title="SMAP server replies">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id696459" shape="rect" name="id696459"> </a>SMAP server replies</h4>
</div>
</div>
</div>
<p>SMAP server replies also (except where noted) are lines of
text terminated by U+000A. There are three general classes of
server replies. All three of them generally contain either
whitespace-delimited words (formatted similarly), or they
begin with one or more whitespace-delimited words, with the
rest being an informative, free-form message.</p>
<p>SMAP servers are allowed to reply with lines of text
terminated by the CR+LF sequence, U+000D U+000A. The ASCII CR
character is interpreted by SMAP clients as whitespace
filler, and is generally ignored. SMAP servers must be
prepared to receive client commands that use either the CR+LF
or the bare LF newline sequence. The only exception to this
rule is the initial connection negotiation, which must use
CR+LF in order to remain compatible with IMAP.</p>
<p>An SMAP client receives the server's response by reading
an entire U+000A-terminated line, then parsing the first
word, or character, to determine the reply's format.</p>
</div>
<div class="section" title="Status replies">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="statusreply" shape="rect" name="statusreply"> </a>Status replies</h4>
</div>
</div>
</div>
<p>A line whose first word is either <span class="quote">“<span class="quote">+OK</span>”</span>
or <span class="quote">“<span class="quote">-ERR</span>”</span> is a <span class="quote">“<span class="quote">status
reply</span>”</span>. <span class="quote">“<span class="quote">+OK</span>”</span>
indicates that the client's request succeeded, <span class="quote">“<span class="quote">-ERR</span>”</span>
indicates that it failed. The rest of the line is a free-form
message, suitable to be displayed as the original command's
acknowledgement. The status reply does not include any actual
information requested by the original command (if any). The
status reply indicates whether the command succeeded or
failed. Information requested by the original command will be
sent before the status reply, using either a "single line",
or a "multiple line" format (see below). A command can result
in more than one single or multi-line reply. The client,
after sending an SMAP command, keeps reading single and
multi-line replies, until a final status reply is read. After
receiving the status reply, the client may proceed to send
the next server command.</p>
<p>The SMAP client must wait until the status reply is
received before sending the next command.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>In order to allow interoperability with IMAP, server
replies prior to logging in are an exception to this reply
format. They follow the general IMAP syntax.</p>
</div>
</div>
<div class="section" title="Single line replies">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="singleline" shape="rect" name="singleline"> </a>Single line replies</h4>
</div>
</div>
</div>
<p>A server reply where the first whitespace-delimited word
is the <span class="quote">“<span class="quote">*</span>”</span> character is called a
<span class="quote">“<span class="quote">single line
reply</span>”</span>. Single line replies send
information, requested by the original command, formatted as
whitespace-delimited words. The information carried by the
words depends on the reply. The actual format of a single
line reply depends on the original command, but can usually
be determined by the word that follows <span class="quote">“<span class="quote">*</span>”</span>.
This single-line reply does not indicate if the client's
command succeeded, the client must still wait to receive the
final status reply. The only exception to this rule is the
initial connection greeting, or the unexpected connection
termination situation, which is described later.</p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>The client must be prepared to receive multiple single
line and multiple line replies, followed by an <span class="quote">“<span class="quote"><code class="literal">-ERR</code></span>”</span> status reply.
This happens when the server encounters an error in a
middle of processing the client's request.</p>
</div>
</div>
<div class="section" title="Multiple line replies">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="multiline" shape="rect" name="multiline"> </a>Multiple line replies</h4>
</div>
</div>
</div>
<p>Certain information returned by an SMAP server cannot be
conveniently represented as a single line of text. An example
would be the contents of a message. Obviously, messages
contains many lines of text. A server reply whose first word
starts with the '{' character is called a <span class="quote">“<span class="quote">multiple line
reply</span>”</span>. This name is actually slightly
misleading; this format may carry binary data that bears no
resemblance to lines of text.</p>
<p>There are two separate multi-line reply formats. The first
format is suitable for line-oriented textual content. It's
called the <span class="quote">“<span class="quote">dot-stuffed format</span>”</span>. The first
word of the server reply is <span class="quote">“<span class="quote">{.<em class="replaceable"><code>nnnn</code></em>}</span>”</span>,
where <span class="quote">“<span class="quote"><em class="replaceable"><code>nnnn</code></em></span>”</span> is
a decimal number. This number is the server's estimate of the
total size of the multi-line reply, in bytes. It is not an
exact byte count, just a reasonable estimate. The server is
not required to compute the exact byte count before sending
the data, just provide a ballpark estimate.</p>
<p>The remaining words of the server's multi-line reply line
contain other information, depending on the nature of the
data. For example, a single SMAP command can request the
server to return the contents of two or more messages. The
server may process those messages in any order. The remainder
of the server's multi-line reply line indicates which message
this multi-line reply refers to. The actual data follows the
server's multi-line reply line. The data is transmitted as
lines of text, each line terminated by the U+000A character.
Servers are also allowed to use the U+000D/U+000A end-of-line
sequence. The end of the data is marked by a line that
contains only a single period, U+002E, followed by optional
whitespace. Lines of data that begin with U+002E have a
second U+002E character prepended.</p>
<p>An SMAP client, upon receiving a multi-line reply in this
format, begins reading U+000A-terminated lines of text, until
it reads a line containing a single U+002E, and optional
whitespace. Other lines with a leading U+002E character have
it removed, and the rest of the line gets saved as the
returned data.</p>
<p>The second multi-line server reply format carries binary
data. It begins with the word <span class="quote">“<span class="quote">{<em class="replaceable"><code>xxxx</code></em>/<em class="replaceable"><code>yyyy</code></em>}</span>”</span>,
where <span class="quote">“<span class="quote"><em class="replaceable"><code>xxxx</code></em></span>”</span> and
<span class="quote">“<span class="quote"><em class="replaceable"><code>yyyy</code></em></span>”</span> are
decimal numbers. <span class="quote">“<span class="quote"><em class="replaceable"><code>yyyy</code></em></span>”</span>
gives the server's estimate of the total size of the binary
data, and <span class="quote">“<span class="quote"><em class="replaceable"><code>xxxx</code></em></span>”</span>
gives the byte count of the first part that the server is
about to send. The server does not have to send everything as
one binary goop. The server is allowed to break down the
binary data in smaller, managable, chunks, which are sent one
at a time.</p>
<p>The remaining words of the multi-line reply line format
are the same as as the dot-stuffed format's. Immediately
following the multi-line reply's trailing U+000A, the server
sends exactly the number of bytes given by <em class="replaceable"><code>xxxx</code></em>. This is called a
"binary chunk".</p>
<p>Each binary chunk is followed by another line of text
terminated by the U+000A character. A trailing line that's
empty, or contains only whitespace, indicates the end of the
multi-line binary data. Otherwise the line contains a single
word, <em class="replaceable"><code>xxxx</code></em> (which
can have leading or trailing whitespace filler), that gives
the byte count of the next binary chunk, which immediately
follows the U+000A character.</p>
<p>The SMAP client reads the initial multi-line reply line,
and obtains the first chunk's byte count, and the estimated
total byte count. The SMAP client then reads the exact number
of bytes indicated by the byte count. Afterwords, the SMAP
client enters a loop where it first reads a
newline-terminated line of text. If the line is empty or
contains only whitespace filler, then this is the end of the
binary data, and the client proceeds to read the next server
reply. Otherwise the client extracts the next chunk's byte
count, reads the indicated number of bytes, then repeats the
process.</p>
</div>
<div class="section" title="An empty multi-line reply">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id697382" shape="rect" name="id697382"> </a>An empty multi-line reply</h4>
</div>
</div>
</div>
<p>An expected multi-line reply may be empty. An example: the
client requests specific E-mail headers, but the message does
not have them. This is indicated by an empty multi-line
reply. An empty multi-line reply is indicated by the word
"{.0}" (followed by the remaining words that specify the
context of this multi-line reply). The next line sent by the
server contains a single "." character. This sequence is
parsed by an SMAP client as a completely empty multi-line
reply.</p>
</div>
</div>
<div class="navfooter">
<hr/>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left" rowspan="1" colspan="1">
<a accesskey="p" href="smap1.html" shape="rect">Prev</a> </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="u" href="smap1.html" shape="rect">Up</a></td>
<td width="40%" align="right" rowspan="1" colspan="1">
 <a accesskey="n" href="conn.html" shape="rect">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top" rowspan="1" colspan="1">Appendix A. Simple Mail Access
Protocol, Version 1 </td>
<td width="20%" align="center" rowspan="1" colspan="1">
<a accesskey="h" href="index.html" shape="rect">Home</a> | <a accesskey="t" href="bk01-toc.html" shape="rect">ToC</a></td>
<td width="40%" align="right" valign="top" rowspan="1" colspan="1"> SMAP connection negotiation</td>
</tr>
</table>
</div>
</body>
</html>
|