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