Google Git
Sign in
chromium / external / gitster / git-htmldocs / bb88cf46ef8a2521a253db9ab576e12202a54fa5 / . / technical / api-run-command.html
blob: 8306e6e1ba84793ed434e235e18b6b2116e06745 [file] [log] [blame]
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]6<meta name="generator" content="AsciiDoc 8.2.5" />
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]7<style type="text/css">
8/* Debug borders */
9p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
10/*
11 border: 1px solid red;
12*/
13}
14
15body {
16 margin: 1em 5% 1em 5%;
17}
18
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]19a {
20 color: blue;
21 text-decoration: underline;
22}
23a:visited {
24 color: fuchsia;
25}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]26
27em {
28 font-style: italic;
29}
30
31strong {
32 font-weight: bold;
33}
34
35tt {
36 color: navy;
37}
38
39h1, h2, h3, h4, h5, h6 {
40 color: #527bbd;
41 font-family: sans-serif;
42 margin-top: 1.2em;
43 margin-bottom: 0.5em;
44 line-height: 1.3;
45}
46
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]47h1, h2, h3 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]48 border-bottom: 2px solid silver;
49}
50h2 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]51 padding-top: 0.5em;
52}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]53h3 {
54 float: left;
55}
56h3 + * {
57 clear: left;
58}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]59
60div.sectionbody {
61 font-family: serif;
62 margin-left: 0;
63}
64
65hr {
66 border: 1px solid silver;
67}
68
69p {
70 margin-top: 0.5em;
71 margin-bottom: 0.5em;
72}
73
74pre {
75 padding: 0;
76 margin: 0;
77}
78
79span#author {
80 color: #527bbd;
81 font-family: sans-serif;
82 font-weight: bold;
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]83 font-size: 1.1em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]84}
85span#email {
86}
87span#revision {
88 font-family: sans-serif;
89}
90
91div#footer {
92 font-family: sans-serif;
93 font-size: small;
94 border-top: 2px solid silver;
95 padding-top: 0.5em;
96 margin-top: 4.0em;
97}
98div#footer-text {
99 float: left;
100 padding-bottom: 0.5em;
101}
102div#footer-badges {
103 float: right;
104 padding-bottom: 0.5em;
105}
106
107div#preamble,
108div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
109div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
110div.admonitionblock {
111 margin-right: 10%;
112 margin-top: 1.5em;
113 margin-bottom: 1.5em;
114}
115div.admonitionblock {
116 margin-top: 2.5em;
117 margin-bottom: 2.5em;
118}
119
120div.content { /* Block element content. */
121 padding: 0;
122}
123
124/* Block element titles. */
125div.title, caption.title {
126 font-family: sans-serif;
127 font-weight: bold;
128 text-align: left;
129 margin-top: 1.0em;
130 margin-bottom: 0.5em;
131}
132div.title + * {
133 margin-top: 0;
134}
135
136td div.title:first-child {
137 margin-top: 0.0em;
138}
139div.content div.title:first-child {
140 margin-top: 0.0em;
141}
142div.content + div.title {
143 margin-top: 0.0em;
144}
145
146div.sidebarblock > div.content {
147 background: #ffffee;
148 border: 1px solid silver;
149 padding: 0.5em;
150}
151
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]152div.listingblock {
153 margin-right: 0%;
154}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]155div.listingblock > div.content {
156 border: 1px solid silver;
157 background: #f4f4f4;
158 padding: 0.5em;
159}
160
161div.quoteblock > div.content {
162 padding-left: 2.0em;
163}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]164
165div.attribution {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]166 text-align: right;
167}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]168div.verseblock + div.attribution {
169 text-align: left;
170}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]171
172div.admonitionblock .icon {
173 vertical-align: top;
174 font-size: 1.1em;
175 font-weight: bold;
176 text-decoration: underline;
177 color: #527bbd;
178 padding-right: 0.5em;
179}
180div.admonitionblock td.content {
181 padding-left: 0.5em;
182 border-left: 2px solid silver;
183}
184
185div.exampleblock > div.content {
186 border-left: 2px solid silver;
187 padding: 0.5em;
188}
189
190div.verseblock div.content {
191 white-space: pre;
192}
193
194div.imageblock div.content { padding-left: 0; }
195div.imageblock img { border: 1px solid silver; }
196span.image img { border-style: none; }
197
198dl {
199 margin-top: 0.8em;
200 margin-bottom: 0.8em;
201}
202dt {
203 margin-top: 0.5em;
204 margin-bottom: 0;
205 font-style: italic;
206}
207dd > *:first-child {
208 margin-top: 0;
209}
210
211ul, ol {
212 list-style-position: outside;
213}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]214div.olist2 ol {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]215 list-style-type: lower-alpha;
216}
217
218div.tableblock > table {
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]219 border: 3px solid #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]220}
221thead {
222 font-family: sans-serif;
223 font-weight: bold;
224}
225tfoot {
226 font-weight: bold;
227}
228
229div.hlist {
230 margin-top: 0.8em;
231 margin-bottom: 0.8em;
232}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]233div.hlist td {
234 padding-bottom: 5px;
235}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]236td.hlist1 {
237 vertical-align: top;
238 font-style: italic;
239 padding-right: 0.8em;
240}
241td.hlist2 {
242 vertical-align: top;
243}
244
245@media print {
246 div#footer-badges { display: none; }
247}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]248
249div#toctitle {
250 color: #527bbd;
251 font-family: sans-serif;
252 font-size: 1.1em;
253 font-weight: bold;
254 margin-top: 1.0em;
255 margin-bottom: 0.1em;
256}
257
258div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
259 margin-top: 0;
260 margin-bottom: 0;
261}
262div.toclevel2 {
263 margin-left: 2em;
264 font-size: 0.9em;
265}
266div.toclevel3 {
267 margin-left: 4em;
268 font-size: 0.9em;
269}
270div.toclevel4 {
271 margin-left: 6em;
272 font-size: 0.9em;
273}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]274/* Workarounds for IE6's broken and incomplete CSS2. */
275
276div.sidebar-content {
277 background: #ffffee;
278 border: 1px solid silver;
279 padding: 0.5em;
280}
281div.sidebar-title, div.image-title {
282 font-family: sans-serif;
283 font-weight: bold;
284 margin-top: 0.0em;
285 margin-bottom: 0.5em;
286}
287
288div.listingblock div.content {
289 border: 1px solid silver;
290 background: #f4f4f4;
291 padding: 0.5em;
292}
293
294div.quoteblock-content {
295 padding-left: 2.0em;
296}
297
298div.exampleblock-content {
299 border-left: 2px solid silver;
300 padding-left: 0.5em;
301}
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]302
303/* IE6 sets dynamically generated links as visited. */
304div#toc a:visited { color: blue; }
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]305</style>
306<title>run-command API</title>
307</head>
308<body>
309<div id="header">
310<h1>run-command API</h1>
311</div>
312<div id="preamble">
313<div class="sectionbody">
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]314<div class="para"><p>The run-command API offers a versatile tool to run sub-processes with
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]315redirected input and output as well as with a modified environment
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]316and an alternate current directory.</p></div>
317<div class="para"><p>A similar API offers the capability to run a function asynchronously,
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]318which is primarily used to capture the output that the function
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]319produces in the caller in order to process it.</p></div>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]320</div>
321</div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]322<h2 id="_functions">Functions</h2>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]323<div class="sectionbody">
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]324<div class="vlist"><dl>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]325<dt>
326<tt>start_command</tt>
327</dt>
328<dd>
329<p>
330 Start a sub-process. Takes a pointer to a <tt>struct child_process</tt>
331 that specifies the details and returns pipe FDs (if requested).
332 See below for details.
333</p>
334</dd>
335<dt>
336<tt>finish_command</tt>
337</dt>
338<dd>
339<p>
340 Wait for the completion of a sub-process that was started with
341 start_command().
342</p>
343</dd>
344<dt>
345<tt>run_command</tt>
346</dt>
347<dd>
348<p>
349 A convenience function that encapsulates a sequence of
350 start_command() followed by finish_command(). Takes a pointer
351 to a <tt>struct child_process</tt> that specifies the details.
352</p>
353</dd>
354<dt>
Junio C Hamanoa476efa2008-10-10 15:31:42[diff] [blame]355<tt>run_command_v_opt</tt>, <tt>run_command_v_opt_cd_env</tt>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]356</dt>
357<dd>
358<p>
359 Convenience functions that encapsulate a sequence of
360 start_command() followed by finish_command(). The argument argv
361 specifies the program and its arguments. The argument opt is zero
Junio C Hamano9f883862009-08-11 06:23:52[diff] [blame]362 or more of the flags <tt>RUN_COMMAND_NO_STDIN</tt>, <tt>RUN_GIT_CMD</tt>,
363 <tt>RUN_COMMAND_STDOUT_TO_STDERR</tt>, or <tt>RUN_SILENT_EXEC_FAILURE</tt>
364 that correspond to the members .no_stdin, .git_cmd,
365 .stdout_to_stderr, .silent_exec_failure of <tt>struct child_process</tt>.
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]366 The argument dir corresponds the member .dir. The argument env
367 corresponds to the member .env.
368</p>
369</dd>
Junio C Hamano9f883862009-08-11 06:23:52[diff] [blame]370</dl></div>
371<div class="para"><p>The functions above do the following:</p></div>
372<div class="olist"><ol>
373<li>
374<p>
375If a system call failed, errno is set and -1 is returned. A diagnostic
376 is printed.
377</p>
378</li>
379<li>
380<p>
381If the program was not found, then -1 is returned and errno is set to
382 ENOENT; a diagnostic is printed only if .silent_exec_failure is 0.
383</p>
384</li>
385<li>
386<p>
387Otherwise, the program is run. If it terminates regularly, its exit
Junio C Hamano167b1382010-01-31 23:04:31[diff] [blame]388 code is returned. No diagnostic is printed, even if the exit code is
Junio C Hamano9f883862009-08-11 06:23:52[diff] [blame]389 non-zero.
390</p>
391</li>
392<li>
393<p>
394If the program terminated due to a signal, then the return value is the
395 signal number - 128, ie. it is negative and so indicates an unusual
396 condition; a diagnostic is printed. This return value can be passed to
397 exit(2), which will report the same code to the parent process that a
398 POSIX shell's $? would report for a program that died from the signal.
399</p>
400<div class="vlist"><dl>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]401<dt>
402<tt>start_async</tt>
403</dt>
404<dd>
405<p>
406 Run a function asynchronously. Takes a pointer to a <tt>struct
Junio C Hamano74a198f2010-02-22 00:13:31[diff] [blame]407 async</tt> that specifies the details and returns a set of pipe FDs
408 for communication with the function. See below for details.
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]409</p>
410</dd>
411<dt>
412<tt>finish_async</tt>
413</dt>
414<dd>
415<p>
Junio C Hamano4f1d8c42008-03-03 02:01:16[diff] [blame]416 Wait for the completion of an asynchronous function that was
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]417 started with start_async().
418</p>
419</dd>
Junio C Hamanocc0cb312009-01-22 03:38:50[diff] [blame]420<dt>
421<tt>run_hook</tt>
422</dt>
423<dd>
424<p>
425 Run a hook.
426 The first argument is a pathname to an index file, or NULL
427 if the hook uses the default index file or no index is needed.
428 The second argument is the name of the hook.
429 The further arguments correspond to the hook arguments.
430 The last argument has to be NULL to terminate the arguments list.
431 If the hook does not exist or is not executable, the return
432 value will be zero.
433 If it is executable, the hook will be executed and the exit
434 status of the hook is returned.
435 On execution, .stdout_to_stderr and .no_stdin will be set.
436 (See below.)
437</p>
438</dd>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]439</dl></div>
Junio C Hamano9f883862009-08-11 06:23:52[diff] [blame]440</li>
441</ol></div>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]442</div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]443<h2 id="_data_structures">Data structures</h2>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]444<div class="sectionbody">
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]445<div class="ilist"><ul>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]446<li>
447<p>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]448<tt>struct child_process</tt>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]449</p>
450</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]451</ul></div>
452<div class="para"><p>This describes the arguments, redirections, and environment of a
453command to run in a sub-process.</p></div>
454<div class="para"><p>The caller:</p></div>
455<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]456<li>
457<p>
Junio C Hamano7562b872008-06-18 03:17:26[diff] [blame]458allocates and clears (memset(&amp;chld, 0, sizeof(chld));) a
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]459 struct child_process variable;
460</p>
461</li>
462<li>
463<p>
464initializes the members;
465</p>
466</li>
467<li>
468<p>
469calls start_command();
470</p>
471</li>
472<li>
473<p>
474processes the data;
475</p>
476</li>
477<li>
478<p>
479closes file descriptors (if necessary; see below);
480</p>
481</li>
482<li>
483<p>
484calls finish_command().
485</p>
486</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]487</ol></div>
488<div class="para"><p>The .argv member is set up as an array of string pointers (NULL
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]489terminated), of which .argv[0] is the program name to run (usually
490without a path). If the command to run is a git command, set argv[0] to
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]491the command name without the <em>git-</em> prefix and set .git_cmd = 1.</p></div>
492<div class="para"><p>The members .in, .out, .err are used to redirect stdin, stdout,
493stderr as follows:</p></div>
494<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]495<li>
496<p>
497Specify 0 to request no special redirection. No new file descriptor
498 is allocated. The child process simply inherits the channel from the
499 parent.
500</p>
501</li>
502<li>
503<p>
504Specify -1 to have a pipe allocated; start_command() replaces -1
505 by the pipe FD in the following way:
506</p>
507<div class="literalblock">
508<div class="content">
509<pre><tt>.in: Returns the writable pipe end into which the caller writes;
510 the readable end of the pipe becomes the child's stdin.</tt></pre>
511</div></div>
512<div class="literalblock">
513<div class="content">
514<pre><tt>.out, .err: Returns the readable pipe end from which the caller
515 reads; the writable end of the pipe end becomes child's
516 stdout/stderr.</tt></pre>
517</div></div>
518<div class="literalblock">
519<div class="content">
520<pre><tt>The caller of start_command() must close the so returned FDs
521after it has completed reading from/writing to it!</tt></pre>
522</div></div>
523</li>
524<li>
525<p>
526Specify a file descriptor &gt; 0 to be used by the child:
527</p>
528<div class="literalblock">
529<div class="content">
530<pre><tt>.in: The FD must be readable; it becomes child's stdin.
531.out: The FD must be writable; it becomes child's stdout.
Junio C Hamano74a198f2010-02-22 00:13:31[diff] [blame]532.err: The FD must be writable; it becomes child's stderr.</tt></pre>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]533</div></div>
534<div class="literalblock">
535<div class="content">
536<pre><tt>The specified FD is closed by start_command(), even if it fails to
537run the sub-process!</tt></pre>
538</div></div>
539</li>
540<li>
541<p>
542Special forms of redirection are available by setting these members
543 to 1:
544</p>
545<div class="literalblock">
546<div class="content">
547<pre><tt>.no_stdin, .no_stdout, .no_stderr: The respective channel is
548 redirected to /dev/null.</tt></pre>
549</div></div>
550<div class="literalblock">
551<div class="content">
Junio C Hamano86bcccc2008-03-08 09:33:55[diff] [blame]552<pre><tt>.stdout_to_stderr: stdout of the child is redirected to its
553 stderr. This happens after stderr is itself redirected.
554 So stdout will follow stderr to wherever it is
555 redirected.</tt></pre>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]556</div></div>
557</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]558</ol></div>
559<div class="para"><p>To modify the environment of the sub-process, specify an array of
560string pointers (NULL terminated) in .env:</p></div>
561<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]562<li>
563<p>
564If the string is of the form "VAR=value", i.e. it contains <em>=</em>
565 the variable is added to the child process's environment.
566</p>
567</li>
568<li>
569<p>
Junio C Hamano4f1d8c42008-03-03 02:01:16[diff] [blame]570If the string does not contain <em>=</em>, it names an environment
571 variable that will be removed from the child process's environment.
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]572</p>
573</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]574</ol></div>
575<div class="para"><p>To specify a new initial working directory for the sub-process,
576specify it in the .dir member.</p></div>
Junio C Hamano9f883862009-08-11 06:23:52[diff] [blame]577<div class="para"><p>If the program cannot be found, the functions return -1 and set
578errno to ENOENT. Normally, an error message is printed, but if
579.silent_exec_failure is set to 1, no message is printed for this
580special error condition.</p></div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]581<div class="ilist"><ul>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]582<li>
583<p>
584<tt>struct async</tt>
585</p>
586</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]587</ul></div>
588<div class="para"><p>This describes a function to run asynchronously, whose purpose is
589to produce output that the caller reads.</p></div>
590<div class="para"><p>The caller:</p></div>
591<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]592<li>
593<p>
Junio C Hamano7562b872008-06-18 03:17:26[diff] [blame]594allocates and clears (memset(&amp;asy, 0, sizeof(asy));) a
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]595 struct async variable;
596</p>
597</li>
598<li>
599<p>
600initializes .proc and .data;
601</p>
602</li>
603<li>
604<p>
605calls start_async();
606</p>
607</li>
608<li>
609<p>
Junio C Hamano74a198f2010-02-22 00:13:31[diff] [blame]610processes communicates with proc through .in and .out;
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]611</p>
612</li>
613<li>
614<p>
Junio C Hamano74a198f2010-02-22 00:13:31[diff] [blame]615closes .in and .out;
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]616</p>
617</li>
618<li>
619<p>
620calls finish_async().
621</p>
622</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]623</ol></div>
Junio C Hamano74a198f2010-02-22 00:13:31[diff] [blame]624<div class="para"><p>The members .in, .out are used to provide a set of fd's for
625communication between the caller and the callee as follows:</p></div>
626<div class="olist"><ol>
627<li>
628<p>
629Specify 0 to have no file descriptor passed. The callee will
630 receive -1 in the corresponding argument.
631</p>
632</li>
633<li>
634<p>
635Specify &lt; 0 to have a pipe allocated; start_async() replaces
636 with the pipe FD in the following way:
637</p>
638<div class="literalblock">
639<div class="content">
640<pre><tt>.in: Returns the writable pipe end into which the caller
641writes; the readable end of the pipe becomes the function's
642in argument.</tt></pre>
643</div></div>
644<div class="literalblock">
645<div class="content">
646<pre><tt>.out: Returns the readable pipe end from which the caller
647reads; the writable end of the pipe becomes the function's
648out argument.</tt></pre>
649</div></div>
650<div class="literalblock">
651<div class="content">
652<pre><tt>The caller of start_async() must close the returned FDs after it
653has completed reading from/writing from them.</tt></pre>
654</div></div>
655</li>
656<li>
657<p>
658Specify a file descriptor &gt; 0 to be used by the function:
659</p>
660<div class="literalblock">
661<div class="content">
662<pre><tt>.in: The FD must be readable; it becomes the function's in.
663.out: The FD must be writable; it becomes the function's out.</tt></pre>
664</div></div>
665<div class="literalblock">
666<div class="content">
667<pre><tt>The specified FD is closed by start_async(), even if it fails to
668run the function.</tt></pre>
669</div></div>
670</li>
671</ol></div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]672<div class="para"><p>The function pointer in .proc has the following signature:</p></div>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]673<div class="literalblock">
674<div class="content">
Junio C Hamano74a198f2010-02-22 00:13:31[diff] [blame]675<pre><tt>int proc(int in, int out, void *data);</tt></pre>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]676</div></div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]677<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]678<li>
679<p>
Junio C Hamano74a198f2010-02-22 00:13:31[diff] [blame]680in, out specifies a set of file descriptors to which the function
681 must read/write the data that it needs/produces. The function
682 <strong>must</strong> close these descriptors before it returns. A descriptor
683 may be -1 if the caller did not configure a descriptor for that
684 direction.
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]685</p>
686</li>
687<li>
688<p>
689data is the value that the caller has specified in the .data member
690 of struct async.
691</p>
692</li>
693<li>
694<p>
695The return value of the function is 0 on success and non-zero
696 on failure. If the function indicates failure, finish_async() will
697 report failure as well.
698</p>
699</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]700</ol></div>
701<div class="para"><p>There are serious restrictions on what the asynchronous function can do
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame^]702because this facility is implemented by a thread in the same address
703space on most platforms (when pthreads is available), but by a pipe to
704a forked process otherwise:</p></div>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]705<div class="olist"><ol>
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]706<li>
707<p>
708It cannot change the program's state (global variables, environment,
Junio C Hamano74a198f2010-02-22 00:13:31[diff] [blame]709 etc.) in a way that the caller notices; in other words, .in and .out
710 are the only communication channels to the caller.
Junio C Hamano6d559fc2008-02-20 10:44:26[diff] [blame]711</p>
712</li>
713<li>
714<p>
715It must not change the program's state that the caller of the
716 facility also uses.
717</p>
718</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]719</ol></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]720</div>
721<div id="footer">
722<div id="footer-text">
Junio C Hamanobb88cf42010-06-21 15:23:55[diff] [blame^]723Last updated 2010-06-21 15:23:42 UTC
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]724</div>
725</div>
726</body>
727</html>