diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-10 00:05:13 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-12-10 00:09:44 +0200 |
commit | e668360caeb54d64b67130f6f4f674d8738a909a (patch) | |
tree | a361085cf1fafee2afa4a89a18b2f4815736a5cd /doc | |
parent | 41c55a1a93840363c996fc9aae54329dadcf0a86 (diff) | |
download | pies-e668360caeb54d64b67130f6f4f674d8738a909a.tar.gz pies-e668360caeb54d64b67130f6f4f674d8738a909a.tar.bz2 |
Update
* doc/macros.texi (xprindex)
(example-output, mtasimopt): Remove
(RFC): New macro.
* doc/pies.texi: Document inetd-style components.
* doc/Makefile.am (fix-sentence-spacing): Fix rule.
* src/progman.c (progman_lookup_tcpmux): Use case-insensitive
comparison, as required by RFC.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile.am | 2 | ||||
-rw-r--r-- | doc/macros.texi | 17 | ||||
-rw-r--r-- | doc/pies.texi | 262 |
3 files changed, 249 insertions, 32 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 73bd72a..21618f0 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am | |||
@@ -144,7 +144,7 @@ fix-sentence-spacing: | |||
144 | do \ | 144 | do \ |
145 | if grep -q '\. [@A-Z]' $$file; then \ | 145 | if grep -q '\. [@A-Z]' $$file; then \ |
146 | mv $$file $${file}~; \ | 146 | mv $$file $${file}~; \ |
147 | sed -r 's/\. ([@A-Z])/. \1/g' $${file}~ > $$file; \ | 147 | sed -r -f fix-sentence-spacing.sed $${file}~ > $$file; \ |
148 | fi; \ | 148 | fi; \ |
149 | done | 149 | done |
150 | 150 | ||
diff --git a/doc/macros.texi b/doc/macros.texi index a26ad0c..bc9fd0a 100644 --- a/doc/macros.texi +++ b/doc/macros.texi | |||
@@ -10,21 +10,8 @@ | |||
10 | @xopindex{\option\, summary} | 10 | @xopindex{\option\, summary} |
11 | @end macro | 11 | @end macro |
12 | 12 | ||
13 | @macro xprindex{option} | 13 | @macro RFC{number} |
14 | @ifclear ANCHOR-PR-\option\ | 14 | @uref{http://tools.ietf.org/html/rfc\number\, RFC \number\} |
15 | @set ANCHOR-PR-\option\ 1 | ||
16 | @anchor{pragma \option\} | ||
17 | @end ifclear | ||
18 | @end macro | ||
19 | |||
20 | @macro example-output{text} | ||
21 | @smallexample | ||
22 | \text\ | ||
23 | @end smallexample | ||
24 | @end macro | ||
25 | |||
26 | @macro mtasimopt{option,text} | ||
27 | @mtindex \option\, --\option\, @r{@command{mtasim} option, \text\} | ||
28 | @end macro | 15 | @end macro |
29 | 16 | ||
30 | 17 | ||
diff --git a/doc/pies.texi b/doc/pies.texi index e21ea62..d5e9d02 100644 --- a/doc/pies.texi +++ b/doc/pies.texi | |||
@@ -126,6 +126,12 @@ Component Statement | |||
126 | * Meta1-Style Components:: | 126 | * Meta1-Style Components:: |
127 | * Component Syntax Summary:: | 127 | * Component Syntax Summary:: |
128 | 128 | ||
129 | Inetd-Style Components | ||
130 | |||
131 | * builtin:: Built-in Inetd Services | ||
132 | * TCPMUX:: TCPMUX Services | ||
133 | * sockenv:: Socket Environment Variables | ||
134 | |||
129 | Global Configuration | 135 | Global Configuration |
130 | 136 | ||
131 | * Less Useful Statements:: | 137 | * Less Useful Statements:: |
@@ -632,6 +638,7 @@ statement. Its value will be available to the program as | |||
632 | @code{argv[0]}. | 638 | @code{argv[0]}. |
633 | @end deffn | 639 | @end deffn |
634 | 640 | ||
641 | @anchor{flags} | ||
635 | @deffn {Config: component} flags (@var{flag-list}) | 642 | @deffn {Config: component} flags (@var{flag-list}) |
636 | Define flags for this component. The @var{flag-list} is a | 643 | Define flags for this component. The @var{flag-list} is a |
637 | comma-separated list of flags. Valid flags are: | 644 | comma-separated list of flags. Valid flags are: |
@@ -662,7 +669,7 @@ This is an internal inetd component. @xref{builtin}. | |||
662 | 669 | ||
663 | @item sockenv | 670 | @item sockenv |
664 | This inetd component wants socket description variables in its | 671 | This inetd component wants socket description variables in its |
665 | environment. @FIXME-xref{sockenv}. | 672 | environment. @xref{sockenv}. |
666 | 673 | ||
667 | @item resolve | 674 | @item resolve |
668 | When used with @samp{sockenv}, the @env{LOCALHOST} and | 675 | When used with @samp{sockenv}, the @env{LOCALHOST} and |
@@ -1075,6 +1082,7 @@ provided that @code{chdir} statement is used for this component | |||
1075 | @end table | 1082 | @end table |
1076 | @end deffn | 1083 | @end deffn |
1077 | 1084 | ||
1085 | @anchor{socket-type} | ||
1078 | @deffn {Config: component} socket-type @var{type} | 1086 | @deffn {Config: component} socket-type @var{type} |
1079 | Sets the socket type. Allowed values for @var{type} are: | 1087 | Sets the socket type. Allowed values for @var{type} are: |
1080 | @samp{stream}, @samp{dgram}, @samp{raw}, @samp{rdm}, | 1088 | @samp{stream}, @samp{dgram}, @samp{raw}, @samp{rdm}, |
@@ -1100,26 +1108,227 @@ opened connections. | |||
1100 | @menu | 1108 | @menu |
1101 | * builtin:: Built-in Inetd Services | 1109 | * builtin:: Built-in Inetd Services |
1102 | * TCPMUX:: TCPMUX Services | 1110 | * TCPMUX:: TCPMUX Services |
1111 | * sockenv:: Socket Environment Variables | ||
1103 | @end menu | 1112 | @end menu |
1104 | 1113 | ||
1105 | @node builtin | 1114 | @node builtin |
1106 | @subsubsection Built-in Inetd Services | 1115 | @subsubsection Built-in Inetd Services |
1107 | @cindex builtin services | 1116 | @cindex builtin services |
1108 | @WRITEME | 1117 | @cindex internal services |
1118 | @dfn{Built-in} or @dfn{internal} services are such inetd-style | ||
1119 | components that are supported internally by @command{pies} and do not | ||
1120 | require external programs. In @command{pies} version @value{VERSION} | ||
1121 | those are: | ||
1122 | |||
1123 | @table @asis | ||
1124 | @cindex echo | ||
1125 | @item echo | ||
1126 | Send back any received data. Defined in @RFC{862}. | ||
1127 | @cindex discard | ||
1128 | @item discard | ||
1129 | Read the data and discard them. Defined in @RFC{863}. | ||
1130 | @cindex time | ||
1131 | @item time | ||
1132 | Return a machine readable date and time as seconds since the Epoch. | ||
1133 | Defined in @RFC{868}. | ||
1134 | @cindex daytime | ||
1135 | @item daytime | ||
1136 | Return current date and time in human-readable format. Defined in | ||
1137 | @RFC{867}. | ||
1138 | @cindex chargen | ||
1139 | @item chargen | ||
1140 | Send a continuous stream of ASCII printable characters without regard | ||
1141 | to the input. Defined in @RFC{864} | ||
1142 | @cindex qotd | ||
1143 | @item qotd | ||
1144 | Send a @samp{quotation of the day} text without regard | ||
1145 | to the input. Defined in @RFC{865}. | ||
1146 | @cindex tcpmux | ||
1147 | @item tcpmux | ||
1148 | TCP Port Service Multiplexer. Defined in @RFC{1078}. | ||
1149 | @end table | ||
1150 | |||
1151 | @cindex @code{internal} flag | ||
1152 | A definition of a built-in service component must | ||
1153 | have the @code{internal} flag (@pxref{flags}). It may not have | ||
1154 | @code{command} or @code{program} statements, as built-in services do | ||
1155 | not need external programs. Instead, it must have a @dfn{service} | ||
1156 | declaration: | ||
1157 | |||
1158 | @deffn {Config: component} service @var{name} | ||
1159 | Set the built-in service name. Its argument is one of the keywords | ||
1160 | listed in the above table. | ||
1161 | @end deffn | ||
1162 | |||
1163 | For example, the following component declaration defines a standard | ||
1164 | TCP-based echo service: | ||
1165 | |||
1166 | @smallexample | ||
1167 | @group | ||
1168 | component echo @{ | ||
1169 | socket "inet://0.0.0.0:echo"; | ||
1170 | service echo; | ||
1171 | flags internal; | ||
1172 | @} | ||
1173 | @end group | ||
1174 | @end smallexample | ||
1175 | |||
1176 | It corresponds to the following @file{inetd.conf} line: | ||
1177 | |||
1178 | @smallexample | ||
1179 | echo stream tcp nowait root internal | ||
1180 | @end smallexample | ||
1181 | |||
1182 | Another built-in services are defined in the same manner, replacing | ||
1183 | @samp{echo} in the @code{service} field with the corresponding service | ||
1184 | name. | ||
1185 | |||
1186 | The @samp{qotd} service reads the contents of the @dfn{qotd file} | ||
1187 | and sends it back to the client. By default the @samp{qotd} file | ||
1188 | is located in the local state directory and named | ||
1189 | @file{@var{instance}.qotd} (where @var{instance} is the name of the | ||
1190 | @command{pies} instance, @FIXME-pxref{instances}). This default location | ||
1191 | can be changed using the following statement: | ||
1192 | |||
1193 | @deffn {Config} qotd-file @var{file-name} | ||
1194 | Set the name of the @samp{quotation-of-the-day} file. | ||
1195 | @end deffn | ||
1196 | |||
1197 | The text read from the @samp{qotd} file is preprocessed, by | ||
1198 | replacing each @acronym{LF} character (@acronym{ASCII} 10) with two | ||
1199 | characters: @acronym{CR} (@acronym{ASCII} 13) followed by | ||
1200 | @acronym{LF}. The resulting text is truncated to 512 characters. | ||
1201 | |||
1202 | The use of @samp{tcpmux} services is covered below. | ||
1109 | 1203 | ||
1110 | @node TCPMUX | 1204 | @node TCPMUX |
1111 | @subsubsection TCPMUX Services | 1205 | @subsubsection TCPMUX Services |
1112 | @cindex TCPMUX | 1206 | @cindex TCPMUX |
1113 | @UNREVISED | 1207 | |
1208 | TCPMUX allows to use multiple services on a single well-known TCP | ||
1209 | port using a service name instead of a well-known number. It is | ||
1210 | defined in @RFC{1078}. The protocol operation is as follows. | ||
1211 | The @dfn{master} TCPMUX component listens on a certain TCP port | ||
1212 | (usually on port 1) for incoming requests. After connecting to the | ||
1213 | master, the client sends the name of the service it wants, followed | ||
1214 | by a carriage-return line-feed (@acronym{CRLF}). @command{Pies} | ||
1215 | looks up this name in the list of services handled by the master | ||
1216 | (@dfn{subordinate services}) and reports with @samp{+} or @samp{-} | ||
1217 | followed by optional text and terminated with the @acronym{CRLF}, | ||
1218 | depending on whether such service name is found or not. If the reply | ||
1219 | was @samp{+}, @command{pies} then starts the requested component. | ||
1220 | Otherwise, it closes the connection. | ||
1221 | |||
1222 | TCPMUX service names are case-insensitive. The special service | ||
1223 | @samp{help} is always defined; it outputs a list of all the | ||
1224 | subordinate services, one name per line, and closes the connection. | ||
1225 | |||
1226 | The master TCPMUX service is declared as a usual built-in service, | ||
1227 | e.g.: | ||
1228 | |||
1229 | @smallexample | ||
1230 | component tcpmux-master @{ | ||
1231 | socket "inet://0.0.0.0:1"; | ||
1232 | service tcpmux; | ||
1233 | flags internal; | ||
1234 | @} | ||
1235 | @end smallexample | ||
1236 | |||
1237 | Any number of subordinate services may be defined for each master. | ||
1238 | A subordinate server component definition must contain at least the | ||
1239 | following statements: | ||
1114 | 1240 | ||
1115 | @deffn {Config: component} service @var{name} | 1241 | @deffn {Config: component} service @var{name} |
1116 | Sets the name of the service for TCPMUX sub-services. | 1242 | Sets the name of the subordinate service. The @var{name} will be compared |