source: project/release/3/osprocess/tags/1.3.1/osprocess-eggdoc.scm @ 11878

Last change on this file since 11878 was 11878, checked in by Kon Lovett, 13 years ago

Needs Unit files.

File size: 17.3 KB
Line 
1;;;; osprocess-eggdoc.scm
2
3(use eggdoc)
4
5(define license #<<EOF
6Copyright (c) 2006, Kon Lovett.  All rights reserved.
7
8Permission is hereby granted, free of charge, to any person obtaining a
9copy of this software and associated documentation files (the Software),
10to deal in the Software without restriction, including without limitation
11the rights to use, copy, modify, merge, publish, distribute, sublicense,
12and/or sell copies of the Software, and to permit persons to whom the
13Software is furnished to do so, subject to the following conditions:
14
15The above copyright notice and this permission notice shall be included
16in all copies or substantial portions of the Software.
17
18THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
21THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
22OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
23ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
24OTHER DEALINGS IN THE SOFTWARE.
25EOF
26)
27
28(define doc `(
29        (eggdoc:begin
30                (name "osprocess")
31                (description (p "Subprocess Object"))
32                (author (url "mailto:klovett@pacbell.net" "Kon Lovett"))
33                (requires
34                  "Chicken 2.6"
35                        miscmacros
36                        misc-extn
37                        synch
38                        job-worker)
39                (usage)
40                (download "osprocess.egg")
41
42                (documentation
43
44                        (p "All query routines will return " (code "(void)") " when the query "
45                        "result is meaningless. Example: the exit-code for a process that hasn't "
46                        "started.")
47
48                        (p "A \"reaper\" task is provided to automatically wait on processes so "
49                        "\"zombies\" are not created from unattended asynchronous processes.")
50
51                        (subsection "Constructors"
52
53                                (procedure "(make-osprocess COMMAND [#:shell? #f] [#:pseudo-tty? #f] [#:reap? #t] [#:fork? #t] [#:wait? #f] [#:exact? #f] [#:search? #f] [#:collect? #f] [#:abnormal-exit-error? #f] [#:signal-mask #f] [#:current-user-id #f] [#:effective-user-id #f] [#:current-group-id #f] [#:effective-group-id #f] [#:output #t] [#:input #t] [#:error #t] [#:output-buffer #f] [#:input-buffer #f] [#:error-buffer #f] [#:output-mode #f] [#:input-mode #f] [#:error-mode #f] [#:arguments #f] [#:environment #f] [ARGUMENT ...])"
54                                        (p "Returns an osprocess object.")
55
56                                        (symbol-table
57                                                (describe COMMAND
58                                                        "The name of the process executable.")
59                                                (describe ARGUMENT
60                                                        "A command-line argument, an object (which will be converted to a string). All arguments and any keyword arguments are combined.")
61                                                (describe #:shell?
62                                                        "Run the process under the system shell? Will construct a command-line from any arguments.")
63                                                (describe #:pseudo-tty?
64                                                        "Run the process with a pseudo-terminal? Either #t or a list of pty name, window width & height.")
65                                                (describe #:reap?
66                                                        "Automatically wait for the process to exit?")
67                                                (describe #:fork?
68                                                        "Create child process? When #f the current process is replaced.")
69                                                (describe #:wait?
70                                                        "Immediately wait for the process to exit? Overrides reaping. Synchronous subprocess.")
71                                                (describe #:exact?
72                                                        "Treat arguments as given when #t. Otherwise argument quoting is performed when constructing a shell command-line.")
73                                                (describe #:search?
74                                                        "Search for the COMMAND pathname when no directory component? A boolean, directory path or list of directory paths. When #t searches using the PATH environment variable, otherwise searches the supplied directory path(s).")
75                                                (describe #:collect?
76                                                        "Automatically collect the stream from input ports? A boolean, procedure or list of boolean or procedure. When a list first element is the input port collector and the seconds is the error port collector. A boolean #f means no collection, #t means use default collector. A procedure must take a single input-port parameter and return some object. The default collector procedure is 'read-all'.")
77                                                (describe #:abnormal-exit-error?
78                                                        "Is an abnormal exit an error? Will raise a process-exception upon abnormal termination.")
79                                                (describe #:signal-mask
80                                                        "List of signals. The signal-mask for the child process.")
81                                                (describe #:current-user-id
82                                                        "The current user id for the child process.")
83                                                (describe #:effective-user-id
84                                                        "The current effective user id for the child process.")
85                                                (describe #:current-group-id
86                                                        "The current group id for the child process.")
87                                                (describe #:effective-group-id
88                                                        "The current effective group id for the child process.")
89                                                (describe #:output
90                                                        "An output-port for the child process stdout, a pathname, a fileno for redirection, #t for pipe, or #f for shared.")
91                                                (describe #:input
92                                                        "An input-port for the child process stdin, a pathname, a fileno for redirection, #t for pipe, or #f for shared.")
93                                                (describe #:error
94                                                        "An output-port for the child process stderr, a pathname, a fileno for redirection, #t for pipe, or #f for shared.")
95                                                (describe #:output-buffer
96                                                        "A buffer size, or a supplied buffer, for the created parent output-port.")
97                                                (describe #:input-buffer
98                                                        "A buffer size, or a supplied buffer, for the created parent input-port.")
99                                                (describe #:error-buffer
100                                                        "A buffer size, or a supplied buffer, for the created parent error-port.")
101                                                (describe #:output-mode
102                                                        "Open mode flags or a list - (<open mode flags> [<creation permission flags>]).")
103                                                (describe #:input-mode
104                                                        "Open mode flags or a list  - (<open mode flags> [<creation permission flags>]).")
105                                                (describe #:error-mode
106                                                        "Open mode flags or a list  - (<open mode flags> [<creation permission flags>]).")
107                                                (describe #:arguments
108                                                        "A list of objects (which will be converted to strings).")
109                                                (describe #:environment
110                                                        "A list of strings (\"ENVVAR=ENVVAL\"), or a list of name-value pairs (which will be converted to strings).") )
111
112          (p "When " (tt "#:shell?") " is " (code "#t") " the " (tt "COMMAND") " "
113          "may be the command-line. In which case the " (tt "#:arguments") " "
114          "must be not be supplied. Should " (tt "#:arguments") " be provided "
115          "the command-line is built from the " (tt "COMMAND") " and the "
116          (tt "#:arguments") ", quoting if necessary. Any " (tt "ARGUMENT") " "
117          "parameters are always passed on as trailing arguments to the shell.")
118
119          (p "The " (tt "#:signal-mask") ", " (tt "#:output-mode") ", "
120          (tt "#:input-mode") ", and " (tt "#:error-mode") " option values require "
121          "the " (code "posix") " unit.")
122
123          (p "The " (tt "#:output-mode") ", " (tt "#:input-mode") ", and "
124          (tt "#:error-mode") " have default open modes of " (code "open/wronly") ", "
125          (code "open/rdonly") ", and " (tt "open/wronly") ", respectively. "
126          "Any other required open mode flags must be supplied.")
127
128                                        (p "The use of " (tt "#:pseudo-tty?") " will ignore the "
129                                        (tt "#:shell?") ", " (tt "#:fork?") ", and " (tt "#:input") ", "
130                                        (tt "#:output") ", " (tt "#:error") " with supplied port.")
131
132          (p "Input stream collection/draining is performed automatically "
133          "when a \"hanging\" process wait is invoked. This is done immediately "
134          "for a synchronous process. Otherwise the programmer must invoke an "
135          (code "osprocess-empty-*") " procedure or wait explicitly for an "
136          "asynchronous process.")
137
138          (p "On Windows the " (tt "#:signal-mask") ", " (tt "#:pseudo-tty?") ", "
139          (tt "#:fork?") ", " (tt "#:input-buffer") ", " (tt "#:output-buffer") ", "
140          (tt "#:error-buffer") ", " (tt "#:input-mode") ", " (tt "#:output-mode") ", "
141          (tt "#:error-mode") ", " (tt "#:input") ", " (tt "#:output") ", "
142          (tt "#:error") " are ignored. The " (tt "#:exact?") " parameter will "
143          "also inhibit argument quoting in all cases, not just command-line "
144          "construction.") )
145
146                                (procedure "(osprocess COMMAND [#:shell? #f] [#:pseudo-tty? #f] [#:reap? #t] [#:fork? #t] [#:wait? #f] [#:exact? #f] [#:search? #f] [#:collect? #f] [#:abnormal-exit-error? #f] [#:signal-mask #f] [#:output #t] [#:input #t] [#:error #t] [#:output-buffer #f] [#:input-buffer #f] [#:error-buffer #f] [#:output-mode #f] [#:input-mode #f] [#:error-mode #f] [#:arguments #f] [#:environment #f] [ARGUMENT ...])"
147                                        (p "Like " (code "make-osprocess") " but starts the process. Returns "
148                                        (code "(values pid input-port output-port error-port osprocess-object)") ".")
149
150                                        (p "Unlike " (code "make-osprocess") " when no arguments are supplied "
151                                        "a shell is automatically used, unless " (tt "#:shell?") " is "
152                                        (code "#f") ".") )
153                        )
154
155                        (subsection "Predicates & Queries"
156
157                                (procedure "(osprocess-list)"
158                                        (p "Returns a list of all the active osprocesses. Once an osprocess "
159                                        "has exited it is removed from the list.") )
160
161                                (procedure "(osprocess? OBJECT)"
162                                        (p "Is the " (tt "OBJECT") " an " (code "osprocess") "?") )
163
164                                (procedure "(osprocess-pseudo-tty? OSPROCESS)"
165                                        (p "Returns either " (code "#f") " when not a pseudo-tty, or a list - "
166                                        (code "(<slave-name> <window-width> <window-height>)") ".") )
167
168                                (procedure "(osprocess-shell? OSPROCESS)"
169                                        (p "Is a shell used to run the process?") )
170
171                                (procedure "(osprocess-forked? OSPROCESS)"
172                                        (p "Is the subprocess to be forked?") )
173
174                                (procedure "(osprocess-waited? OSPROCESS)"
175                                        (p "Is the subprocess to be synchronous?") )
176
177                                (procedure "(osprocess-started? OSPROCESS)"
178                                        (p "Has the process started?") )
179
180                                (procedure "(osprocess-running? OSPROCESS)"
181                                        (p "Is the process alive?") )
182
183                                (procedure "(osprocess-alive? OSPROCESS)"
184                                        (p "Is the process alive?") )
185
186                                (procedure "(osprocess-exited? OSPROCESS)"
187                                        (p "Has the process exited?") )
188
189                                (procedure "(osprocess-command OSPROCESS)"
190                                        (p "Returns the process command pathname or command-line, depending on "
191                                        "whether a shell used to run the process.") )
192
193                                (procedure "(osprocess-arguments OSPROCESS)"
194                                        (p "Returns the process arguments or " (code "#f") ". This can be "
195                                        (code "#f") " even when arguments were supplied due to the use of a "
196                                        "shell to run the process.") )
197
198                                (procedure "(osprocess-environment OSPROCESS)"
199                                        (p "Returns the process environment or " (code "#f") ".") )
200
201                                (procedure "(osprocess-pid OSPROCESS)"
202                                        (p "Returns the system identifier for this process.") )
203
204                                (procedure "(osprocess-start-seconds OSPROCESS)"
205                                        (p "When was the process started (approximate).") )
206
207                                (procedure "(osprocess-exit-seconds OSPROCESS)"
208                                        (p "When did the process exit (very approximate).") )
209
210                                (procedure "(osprocess-exit-normal? OSPROCESS)"
211                                        (p "Did the process exit normally?") )
212
213                                (procedure "(osprocess-exit-code OSPROCESS)"
214                                        (p "Returns the process exit status or signal.") )
215
216                                (procedure "(osprocess-exit-status OSPROCESS)"
217                                        (p "Returns the process exit status or " (code "#f") " when abnormal "
218                                        "exit.") )
219
220                                (procedure "(osprocess-exit-signal OSPROCESS)"
221                                        (p "Returns the process exit signal or " (code "#f") " when normal "
222                                        "exit.") )
223
224                                (procedure "(osprocess-input-port OSPROCESS)"
225                                        (p "Returns the stdin input port or " (code "#f") " when a "
226                                        "port specification was supplied.") )
227
228                                (procedure "(osprocess-output-port OSPROCESS)"
229                                        (p "Returns the stdout output port or " (code "#f") " when a "
230                                        "port specification was supplied.") )
231
232                                (procedure "(osprocess-error-port OSPROCESS)"
233                                        (p "Returns the stderr input port or " (code "#f") " when a "
234                                        "port specification was supplied.") )
235
236                                (procedure "(osprocess-ports OSPROCESS)"
237                                        (p "Returns " (code "(values input-port output-port error-port)") ".") )
238
239                                (procedure "(osprocess-connection OSPROCESS)"
240                                        (p "Returns " (code "(values pid input-port output-port error-port)") ".") )
241
242                                (procedure "(osprocess-input-port-collection OSPROCESS)"
243                                        (p "The collected output object for the input-port.") )
244
245                                (procedure "(osprocess-error-port-collection OSPROCESS)"
246                                        (p "The collected output object for the error-port.") )
247
248                                (procedure "(osprocess-error OSPROCESS)"
249                                        (p "Returns the last captured exception and resets to " (code "#f") ".") )
250                        )
251
252                        (subsection "Queries & Modifiers"
253
254                                (procedure "(osprocess-priority OSPROCESS [PRIORITY])"
255                                        (p "Gets or sets the process priority. " (tt "PRIORITY") " must be an "
256                                        "integer [-20 20] to set the priority.")
257
258                                        (p "Note that only the superuser can lower a priority.") )
259
260        #; ; Unused
261                                (procedure "(osprocess-autoclose-input-port OSPROCESS [FLAG])"
262                                        (p "Gets or sets the automatic close operation for the "
263                                        "input-port upon process exit.") )
264
265        #; ; Unused
266                                (procedure "(osprocess-autoclose-output-port OSPROCESS [FLAG])"
267                                        (p "Gets or sets the automatic close operation for the "
268                                        "output-port upon process exit.") )
269
270        #; ; Unused
271                                (procedure "(osprocess-autoclose-error-port OSPROCESS [FLAG])"
272                                        (p "Gets or sets the automatic close operation for the "
273                                        "error-port upon process exit.") )
274
275        #; ; Unused
276                                (procedure "(osprocess-autoclose-ports OSPROCESS [FLAG])"
277                                        (p "Gets or sets the automatic close operation for the "
278                                        "ports upon process exit.") )
279
280                                (procedure "(osprocess-collect-input-port OSPROCESS [COLLECTOR])"
281                                        (p "Gets or sets the automatic collection operation for the input-port "
282                                        "output stream using the specified " (tt "COLLECTOR") ". When "
283                                        (tt "COLLECTOR") " is " (code "#f") " collecting is disabled, when " (code "#t")
284                                        " the default is used. Otherwise the " (tt "COLLECTOR") " must be a "
285                                        "procedure of one argument, an " (code "input-port") ", and returning "
286                                        "some object, usually a " (code "string") ".") )
287
288                                (procedure "(osprocess-collect-error-port OSPROCESS [COLLECTOR])"
289                                  (p "Like " (code "osprocess-collect-input-port") " but for the "
290                                  "error-port.") )
291
292                                (procedure "(osprocess-collect-ports OSPROCESS [COLLECTOR])"
293                                  (p "Like " (code "osprocess-collect-input-port") " but for the "
294                                  "input-port & error-port.") )
295                        )
296
297                        (subsection "Actions"
298
299                                (procedure "(osprocess-empty-input-port OSPROCESS)"
300                                  (p "Drains or collects the input port of a started " (tt "OSPROCESS") ".") )
301
302                                (procedure "(osprocess-empty-error-port OSPROCESS)"
303                                  (p "Drains or collects the error port of a started " (tt "OSPROCESS") ".") )
304
305                                (procedure "(osprocess-empty-ports OSPROCESS)"
306                                  (p "Drains or collects the input & error ports of a started " (tt "OSPROCESS") ".") )
307
308                                (procedure "(osprocess-close-input-port OSPROCESS)"
309                                        (p "Closes a created input-port.") )
310
311                                (procedure "(osprocess-close-output-port OSPROCESS)"
312                                        (p "Closes a created output-port.") )
313
314                                (procedure "(osprocess-close-error-port OSPROCESS)"
315                                        (p "Closes a created error-port.") )
316
317                                (procedure "(osprocess-close-ports OSPROCESS)"
318                                        (p "Closes all created ports.") )
319
320                                (procedure "(osprocess-run OSPROCESS)"
321                                        (p "Starts the osprocess and returns "
322                                        (code "(values pid input-port output-port error-port)") ".") )
323
324                                (procedure "(osprocess-wait OSPROCESS [NOHANG #f])"
325                                        (p "Waits, or not, depending on " (tt "NOHANG") ", for the osprocess to "
326                                        "exit. Returns " (code "(values pid exit-normal? exit-code)") ", where "
327                                        "pid is 0 when the osprocess has not exited.") )
328
329                                (procedure "(osprocess-wait-any [NOHANG #f])"
330                                        (p "Waits for any osprocess to exit. Returns the osprocess that "
331                                        "exited or " (code "#f") " when an osprocess has not exited.")
332
333                                        (p "Currently this waits on " (b "any") " child process, not just "
334                                        "osprocesses!") )
335
336                                (procedure "(osprocess-kill OSPROCESS [FORCE? #f])"
337                                        (p "On UNIX systems sends " (code "signal/term") " to the process, "
338                                        "unless " (tt "FORCE?") " is " (code "#t") " in which case "
339                                        (code "signal/kill") " is sent.") )
340
341                                (procedure "(osprocess-stop OSPROCESS)"
342                                        (p "On UNIX systems sends " (code "signal/stop") " to the osprocess.") )
343
344                                (procedure "(osprocess-continue OSPROCESS)"
345                                        (p "On UNIX systems sends " (code "signal/cont") " to the osprocess.") )
346
347                                (procedure "(osprocess-signal OSPROCESS SIGNAL)"
348                                        (p "On UNIX systems sends " (tt "SIGNAL") " to the osprocess.") )
349                        )
350
351                        (subsection "Reaper Procedures"
352
353                                (parameter "(osprocess-reaper-period [SECONDS 10.0])"
354                                        (p "How many seconds between checking for zombies. Will take effect "
355                                        "when the reaper resets or starts.") )
356
357                                (procedure "(osprocess-reap OSPROCESS [FLAG])"
358                                        (p "Gets or sets the reaping operation.") )
359
360                                (procedure "(osprocess:remove-sigchld-handler)"
361                                        (p "Removes the SIGCHLD handler. Do not call this unless "
362                                        "absolutely necessary.") )
363                        )
364    )
365
366    (section "Issues"
367
368      (p "Do " (b "not") " modify the definition values; copies are neither "
369      "kept nor returned!")
370
371      (p "Use of a shell will cause the " (code "osprocess-command") " and "
372      (code "osprocess-arguments") " queries to reflect the execution values, "
373      "not the definition values.")
374
375      (p "Incomplete Windows support.")
376    )
377
378                (history
379                  (version "1.3.1" "Needs Unit files.")
380                  (version "1.3" "Use of misc-extn 3.1 procedures. Added user/group id setting.")
381                        (version "1.2" "Added collect?, search? & exact? option keywords. Added automatic input stream draining. Made osprocess result values order like osprocess-run result")
382                        (version "1.1" "Added fileno redirection")
383                        (version "1.0" "Initial release") )
384
385    (section "License" (pre ,license))
386  )
387))
388
389(eggdoc->html doc)
Note: See TracBrowser for help on using the repository browser.