/usr/share/doc/gnats/gnats/gnatsd-command-protocol.html is in gnats 4.1.0-2.
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 | <html lang="en">
<head>
<title>gnatsd command protocol - Keeping Track</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Keeping Track">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="gnatsd.html#gnatsd" title="gnatsd">
<link rel="prev" href="gnatsd-options.html#gnatsd-options" title="gnatsd options">
<link rel="next" href="gnatsd-commands.html#gnatsd-commands" title="gnatsd commands">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="gnatsd-command-protocol"></a>
<p>
Next: <a rel="next" accesskey="n" href="gnatsd-commands.html#gnatsd-commands">gnatsd commands</a>,
Previous: <a rel="previous" accesskey="p" href="gnatsd-options.html#gnatsd-options">gnatsd options</a>,
Up: <a rel="up" accesskey="u" href="gnatsd.html#gnatsd">gnatsd</a>
<hr>
</div>
<h3 class="section">B.3 <code>gnatsd</code> command protocol</h3>
<p><a name="index-g_t_0040code_007bgnatsd_007d-command-protocol-377"></a>
Commands are issued to <code>gnatsd</code> as one or more words followed by a
carriage-return/linefeed pair. For example, the <code>CHDB</code> (change
database) command is sent as ‘<samp><span class="samp">CHDB database<CR><LF></span></samp>’ (the
<code>CRLF</code> will not be explicitly written for future examples.)
<p>Replies from <code>gnatsd</code> are returned as one or more response lines
containing a 3-digit numeric code followed by a human-readable string;
the line is terminated with a <code><CR><LF></code> pair. For example, one
possible response to the <code>CHDB</code> command above would be:
<pre class="smallexample"> 210 Now accessing GNATS database 'database'.
</pre>
<p>The three-digit code is normally followed by a single ASCII space
(character 0x20). However, if additional response lines are to be
returned from the server, there will be a single dash ‘<samp><span class="samp">-</span></samp>’ instead
of the space character after the three-digit code.
<p>Response code values are divided into ranges. The first digit reflects
the general type of response (such as ”successful” or ”error”), and
the subsequent digits identify the specific type of response.
<dl>
<dt><var>Codes 200-299</var><dd>Positive response indicating that the command was successful. No
subsequent data will be transmitted with the response. In particular,
code 210 (<code>CODE_OK</code>) is used as the positive result code for most
simple commands.
<p>Commands that expect additional data from the client (such as
<code>SUBM</code> or <code>VFLD</code>) use a two-step mechanism for sending the
data. The server will respond to the initial command with either a 211
(<code>CODE_SEND_PR</code>) or 212 (<code>CODE_SEND_TEXT</code>) response line, or
an error code if an error occurred with the initial command. The client
is then expected to send the remaining data using the same quoting
mechanism as described for server responses in the 300-349 range. The
server will then send a final response line to the command.
<br><dt><var>Codes 300-399</var><dd>Positive response indicating that the query request was successful, and
that a PR or other data will follow. Codes 300-349 are used when
transmitting PRs, and 350-399 are used for other responses.
<p>Codes in the 300-349 range are followed by a series of
<code>CRLF</code>-terminated lines containing the command response, usually a
PR. The final line of the result is a single period ‘<samp><span class="samp">.</span></samp>’. Result
lines that begin with a period have an extra period prepended to them.
<p>Codes in the 350-399 range use a different scheme for sending their
responses. The three-digit numeric code will be followed by either a
dash ‘<samp><span class="samp">-</span></samp>’ or a single space. If the code is followed by a dash,
that indicates that another response line will follow. The final line
of the response has a single space after the three-digit code.
<p>In previous versions of the protocol the first line of a
<code>CODE_INFORMATION</code> (310) response was to be ignored. This is no
longer the case. Instead, any lines marked with code
<code>CODE_INFORMATION_FILLER</code> (351) are to be ignored. This allows the
server to transmit additional headers or other human-readable text that
can be safely ignored by the clients.
<br><dt><var>Codes 400-599</var><dd>An error occurred, usually because of invalid command parameters or
invalid input from the client, missing arguments to the command, or a
command was issued out of sequence. The human-readable message
associated with the response line describes the general problem
encountered with the command.
<p>Multiple error messages may be returned from a command; in this case the
‘<samp><span class="samp">-</span></samp>’ continuation character is used on all but the last response
line.
<br><dt><var>Codes 600-799</var><dd>An internal error occurred on the server, a timeout occurred reading
data from the client, or a network failure occurred. These errors are
of the ”this should not occur” nature, and retrying the operation may
resolve the problem. Fortunately, most <span class="sc">gnats</span> transactions are
idempotent; unfortunately, locking the database or a PR are not
repeatable actions (we cannot determine if an existing lock is the one
we originally requested, or someone else's).
</dl>
</body></html>
|