Remotes configuration API

From 6d559fc736bece9bac0d731b496639cbfe9ef757 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 20 Feb 2008 10:44:26 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.5.4.2-156-ge3c5 --- git-pull.html | 53 ++-- git-pull.txt | 20 +- git-push.html | 83 +++++- git-push.txt | 55 +++- technical/api-index.html | 7 +- technical/api-index.txt | 1 + technical/api-remote.html | 443 +++++++++++++++++++++++++++++++++ technical/api-remote.txt | 123 +++++++++ technical/api-run-command.html | 291 +++++++++++++++++++++- technical/api-run-command.txt | 171 ++++++++++++- 10 files changed, 1194 insertions(+), 53 deletions(-) create mode 100644 technical/api-remote.html create mode 100644 technical/api-remote.txt diff --git a/git-pull.html b/git-pull.html index 8f555da6c..0cc70849b 100644 --- a/git-pull.html +++ b/git-pull.html @@ -277,7 +277,8 @@ git-pull(1) Manual Page

DESCRIPTION

Runs git-fetch with the given parameters, and calls git-merge -to merge the retrieved head(s) into the current branch.

+to merge the retrieved head(s) into the current branch. +With --rebase, calls git-rebase instead of git-merge.

Note that you can use . (current directory) as the <repository> to pull from the local repository — this is useful when merging local branches into the current branch.

@@ -378,6 +379,31 @@ when merging local branches into the current branch.

+--rebase +

+ Instead of a merge, perform a rebase after fetching. If + there is a remote ref for the upstream branch, and this branch + was rebased since last fetched, the rebase uses that information + to avoid rebasing non-local changes. To make this the default + for branch <name>, set configuration branch.<name>.rebase + to true. +

NOTE: This is a potentially _dangerous_ mode of operation. +It rewrites history, which does not bode well when you +published that history already. Do not use this option +unless you have read git-rebase(1) carefully.

+--no-rebase +

+ Override earlier --rebase. +

-q, --quiet

@@ -785,29 +811,6 @@ ours branches.

---rebase -

- Instead of a merge, perform a rebase after fetching. If - there is a remote ref for the upstream branch, and this branch - was rebased since last fetched, the rebase uses that information - to avoid rebasing non-local changes. -

NOTE: This is a potentially _dangerous_ mode of operation. -It rewrites history, which does not bode well when you -published that history already. Do not use this option -unless you have read git-rebase(1) carefully.

---no-rebase -

- Override earlier --rebase. -

DEFAULT BEHAVIOUR

@@ -970,7 +973,7 @@ Junio C Hamano and the git-list <git@vger.kernel.org>.

diff --git a/git-pull.txt b/git-pull.txt index 179bdfc69..737894390 100644 --- a/git-pull.txt +++ b/git-pull.txt @@ -15,6 +15,7 @@ DESCRIPTION ----------- Runs `git-fetch` with the given parameters, and calls `git-merge` to merge the retrieved head(s) into the current branch. +With `--rebase`, calls `git-rebase` instead of `git-merge`. Note that you can use `.` (current directory) as the to pull from the local repository -- this is useful @@ -26,19 +27,14 @@ OPTIONS include::merge-options.txt[] :git-pull: 1 -include::fetch-options.txt[] - -include::pull-fetch-param.txt[] - -include::urls-remotes.txt[] - -include::merge-strategies.txt[] \--rebase:: Instead of a merge, perform a rebase after fetching. If there is a remote ref for the upstream branch, and this branch was rebased since last fetched, the rebase uses that information - to avoid rebasing non-local changes. + to avoid rebasing non-local changes. To make this the default + for branch ``, set configuration `branch..rebase` + to `true`. + *NOTE:* This is a potentially _dangerous_ mode of operation. It rewrites history, which does not bode well when you @@ -48,6 +44,14 @@ unless you have read linkgit:git-rebase[1] carefully. \--no-rebase:: Override earlier \--rebase. +include::fetch-options.txt[] + +include::pull-fetch-param.txt[] + +include::urls-remotes.txt[] + +include::merge-strategies.txt[] + DEFAULT BEHAVIOUR ----------------- diff --git a/git-push.html b/git-push.html index a2f60173b..6ada41e4a 100644 --- a/git-push.html +++ b/git-push.html @@ -316,9 +316,9 @@ the optional plus + is used, the remote ref is updated even if it does not result in a fast forward update.

Note: If no explicit refspec is found, (that is neither on the command line nor in any Push line of the -corresponding remotes file---see below), then all the -heads that exist both on the local side and on the remote -side are updated.

+corresponding remotes file---see below), then "matching" heads are +pushed: for every head that exists on the local side, the remote side is +updated if a head of the same name already exists on the remote side.

tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>.

A parameter <ref> without a colon pushes the <ref> from the source repository to the destination repository under the same name.

@@ -572,6 +572,81 @@ corresponding file in the $GIT_DIR/remotes/ directory.

Pull: refs/heads/<head>:<remote> +

OUTPUT

The output of "git push" depends on the transport method used; this +section describes the output when pushing over the git protocol (either +locally or via ssh).

The status of the push is output in tabular form, with each line +representing the status of a single ref. Each line is of the form:

 <flag> <summary> <from> -> <to> (<reason>)

+flag +: +
+ A single character indicating the status of the ref. This is + blank for a successfully pushed ref, ! for a ref that was + rejected or failed to push, and = for a ref that was up to + date and did not need pushing (note that the status of up to + date refs is shown only when git push is running verbosely). +
+
+summary +: +
+ For a successfully pushed ref, the summary shows the old and new + values of the ref in a form suitable for using as an argument to + git log (this is <old>..<new> in most cases, and + <old>…<new> for forced non-fast forward updates). For a + failed update, more details are given for the failure. + The string rejected indicates that git did not try to send the + ref at all (typically because it is not a fast forward). The + string remote rejected indicates that the remote end refused + the update; this rejection is typically caused by a hook on the + remote side. The string remote failure indicates that the + remote end did not report the successful update of the ref + (perhaps because of a temporary error on the remote side, a + break in the network connection, or other transient error). +
+
+from +: +
+ The name of the local ref being pushed, minus its + refs/<type>/ prefix. In the case of deletion, the + name of the local ref is omitted. +
+
+to +: +
+ The name of the remote ref being updated, minus its + refs/<type>/ prefix. +
+
+reason +: +
+ A human-readable explanation. In the case of successfully pushed + refs, no explanation is needed. For a failed ref, the reason for + failure is described. +
+

Examples

@@ -634,7 +709,7 @@ by Linus Torvalds <torvalds@osdl.org>

diff --git a/git-push.txt b/git-push.txt index 5f2494495..3128170bc 100644 --- a/git-push.txt +++ b/git-push.txt @@ -47,9 +47,9 @@ even if it does not result in a fast forward update. + Note: If no explicit refspec is found, (that is neither on the command line nor in any Push line of the -corresponding remotes file---see below), then all the -heads that exist both on the local side and on the remote -side are updated. +corresponding remotes file---see below), then "matching" heads are +pushed: for every head that exists on the local side, the remote side is +updated if a head of the same name already exists on the remote side. + `tag ` means the same as `refs/tags/:refs/tags/`. + @@ -108,6 +108,55 @@ the remote repository. include::urls-remotes.txt[] +OUTPUT +------ + +The output of "git push" depends on the transport method used; this +section describes the output when pushing over the git protocol (either +locally or via ssh). + +The status of the push is output in tabular form, with each line +representing the status of a single ref. Each line is of the form: + +------------------------------- +

-> () +------------------------------- + +flag:: + A single character indicating the status of the ref. This is + blank for a successfully pushed ref, `!` for a ref that was + rejected or failed to push, and '=' for a ref that was up to + date and did not need pushing (note that the status of up to + date refs is shown only when `git push` is running verbosely). + +summary:: + For a successfully pushed ref, the summary shows the old and new + values of the ref in a form suitable for using as an argument to + `git log` (this is `..` in most cases, and + `...` for forced non-fast forward updates). For a + failed update, more details are given for the failure. + The string `rejected` indicates that git did not try to send the + ref at all (typically because it is not a fast forward). The + string `remote rejected` indicates that the remote end refused + the update; this rejection is typically caused by a hook on the + remote side. The string `remote failure` indicates that the + remote end did not report the successful update of the ref + (perhaps because of a temporary error on the remote side, a + break in the network connection, or other transient error). + +from:: + The name of the local ref being pushed, minus its + `refs//` prefix. In the case of deletion, the + name of the local ref is omitted. + +to:: + The name of the remote ref being updated, minus its + `refs//` prefix. + +reason:: + A human-readable explanation. In the case of successfully pushed + refs, no explanation is needed. For a failed ref, the reason for + failure is described. Examples -------- diff --git a/technical/api-index.html b/technical/api-index.html index 173a1e2d9..58fc703f9 100644 --- a/technical/api-index.html +++ b/technical/api-index.html @@ -338,6 +338,11 @@ documents them.

+Remotes configuration API +

revision walking API

@@ -372,7 +377,7 @@ documents them.

diff --git a/technical/api-index.txt b/technical/api-index.txt index bc9c190a9..6c272fc08 100644 --- a/technical/api-index.txt +++ b/technical/api-index.txt @@ -21,6 +21,7 @@ documents them. * link:api-parse-options.html[parse-options API] * link:api-path-list.html[path-list API] * link:api-quote.html[quote API] +* link:api-remote.html[Remotes configuration API] * link:api-revision-walking.html[revision walking API] * link:api-run-command.html[run-command API] * link:api-setup.html[setup API] diff --git a/technical/api-remote.html b/technical/api-remote.html new file mode 100644 index 000000000..a796310be --- /dev/null +++ b/technical/api-remote.html @@ -0,0 +1,443 @@ + + + + + + +Remotes configuration API + + + +

The API in remote.h gives access to the configuration related to +remotes. It handles all three configuration mechanisms historically +and currently used by git, and presents the information in a uniform +fashion. Note that the code also handles plain URLs without any +configuration, giving them just the default information.

struct remote

+name +: +
+ The user's nickname for the remote +
+
+url +: +
+ An array of all of the url_nr URLs configured for the remote +
+
+push +: +
+ An array of refspecs configured for pushing, with + push_refspec being the literal strings, and push_refspec_nr + being the quantity. +
+
+fetch +: +
+ An array of refspecs configured for fetching, with + fetch_refspec being the literal strings, and fetch_refspec_nr + being the quantity. +
+
+fetch_tags +: +
+ The setting for whether to fetch tags (as a separate rule from + the configured refspecs); -1 means never to fetch tags, 0 + means to auto-follow tags based on the default heuristic, 1 + means to always auto-follow tags, and 2 means to fetch all + tags. +
+
+receivepack, uploadpack +: +
+ The configured helper programs to run on the remote side, for + git-native protocols. +
+
+http_proxy +: +
+ The proxy to use for curl (http, https, ftp, etc.) URLs. +
+

struct remotes can be found by name with remote_get(), and iterated +through with for_each_remote(). remote_get(NULL) will return the +default remote, given the current branch and configuration.

struct refspec

A struct refspec holds the parsed interpretation of a refspec. If it +will force updates (starts with a +), force is true. If it is a +pattern (sides end with *) pattern is true. src and dest are the two +sides (if a pattern, only the part outside of the wildcards); if there +is only one side, it is src, and dst is NULL; if sides exist but are +empty (i.e., the refspec either starts or ends with :), the +corresponding side is "".

This parsing can be done to an array of strings to give an array of +struct refpsecs with parse_ref_spec().

remote_find_tracking(), given a remote and a struct refspec with +either src or dst filled out, will fill out the other such that the +result is in the "fetch" specification for the remote (note that this +evaluates patterns and returns a single result).

struct branch

Note that this may end up moving to branch.h

struct branch holds the configuration for a branch. It can be looked +branch_get(NULL) for HEAD.

It contains:

+name +: +
+ The short name of the branch. +
+
+refname +: +
+ The full path for the branch ref. +
+
+remote_name +: +
+ The name of the remote listed in the configuration. +
+
+remote +: +
+ The struct remote for that remote. +
+
+merge_name +: +
+ An array of the "merge" lines in the configuration. +
+
+merge +: +
+ An array of the struct refspecs used for the merge lines. That + is, merge[i]->dst is a local tracking ref which should be + merged into this branch by default. +
+
+merge_nr +: +
+ The number of merge configurations +
+

branch_has_merge_config() returns true if the given branch has merge +configuration given.

Other stuff

There is other stuff in remote.h that is related, in general, to the +process of interacting with remotes.

(Daniel Barkalow)

+ + + diff --git a/technical/api-remote.txt b/technical/api-remote.txt new file mode 100644 index 000000000..073b22bd8 --- /dev/null +++ b/technical/api-remote.txt @@ -0,0 +1,123 @@ +Remotes configuration API +========================= + +The API in remote.h gives access to the configuration related to +remotes. It handles all three configuration mechanisms historically +and currently used by git, and presents the information in a uniform +fashion. Note that the code also handles plain URLs without any +configuration, giving them just the default information. + +struct remote +------------- + +`name`:: + + The user's nickname for the remote + +`url`:: + + An array of all of the url_nr URLs configured for the remote + +`push`:: + + An array of refspecs configured for pushing, with + push_refspec being the literal strings, and push_refspec_nr + being the quantity. + +`fetch`:: + + An array of refspecs configured for fetching, with + fetch_refspec being the literal strings, and fetch_refspec_nr + being the quantity. + +`fetch_tags`:: + + The setting for whether to fetch tags (as a separate rule from + the configured refspecs); -1 means never to fetch tags, 0 + means to auto-follow tags based on the default heuristic, 1 + means to always auto-follow tags, and 2 means to fetch all + tags. + +`receivepack`, `uploadpack`:: + + The configured helper programs to run on the remote side, for + git-native protocols. + +`http_proxy`:: + + The proxy to use for curl (http, https, ftp, etc.) URLs. + +struct remotes can be found by name with remote_get(), and iterated +through with for_each_remote(). remote_get(NULL) will return the +default remote, given the current branch and configuration. + +struct refspec +-------------- + +A struct refspec holds the parsed interpretation of a refspec. If it +will force updates (starts with a '+'), force is true. If it is a +pattern (sides end with '*') pattern is true. src and dest are the two +sides (if a pattern, only the part outside of the wildcards); if there +is only one side, it is src, and dst is NULL; if sides exist but are +empty (i.e., the refspec either starts or ends with ':'), the +corresponding side is "". + +This parsing can be done to an array of strings to give an array of +struct refpsecs with parse_ref_spec(). + +remote_find_tracking(), given a remote and a struct refspec with +either src or dst filled out, will fill out the other such that the +result is in the "fetch" specification for the remote (note that this +evaluates patterns and returns a single result). + +struct branch +------------- + +Note that this may end up moving to branch.h + +struct branch holds the configuration for a branch. It can be looked +up with branch_get(name) for "refs/heads/{name}", or with +branch_get(NULL) for HEAD. + +It contains: + +`name`:: + + The short name of the branch. + +`refname`:: + + The full path for the branch ref. + +`remote_name`:: + + The name of the remote listed in the configuration. + +`remote`:: + + The struct remote for that remote. + +`merge_name`:: + + An array of the "merge" lines in the configuration. + +`merge`:: + + An array of the struct refspecs used for the merge lines. That + is, merge[i]->dst is a local tracking ref which should be + merged into this branch by default. + +`merge_nr`:: + + The number of merge configurations + +branch_has_merge_config() returns true if the given branch has merge +configuration given. + +Other stuff +----------- + +There is other stuff in remote.h that is related, in general, to the +process of interacting with remotes. + +(Daniel Barkalow) diff --git a/technical/api-run-command.html b/technical/api-run-command.html index 1f192a9ed..98ecb6a4e 100644 --- a/technical/api-run-command.html +++ b/technical/api-run-command.html @@ -263,30 +263,307 @@ div.exampleblock-content {

Talk about <run-command.h>, and things like:

The run-command API offers a versatile tool to run sub-processes with +redirected input and output as well as with a modified environment +and an alternate current directory.

A similar API offers the capability to run a function asynchronously, +which is primarily used to capture the output that the function +produces in the caller in order to process it.

Functions

+start_command +: +
+ Start a sub-process. Takes a pointer to a struct child_process + that specifies the details and returns pipe FDs (if requested). + See below for details. +
+
+finish_command +: +
+ Wait for the completion of a sub-process that was started with + start_command(). +
+
+run_command +: +
+ A convenience function that encapsulates a sequence of + start_command() followed by finish_command(). Takes a pointer + to a struct child_process that specifies the details. +
+
+run_command_v_opt, run_command_v_opt_dir, run_command_v_opt_cd_env +: +
+ Convenience functions that encapsulate a sequence of + start_command() followed by finish_command(). The argument argv + specifies the program and its arguments. The argument opt is zero + or more of the flags RUN_COMMAND_NO_STDIN, RUN_GIT_CMD, or + RUN_COMMAND_STDOUT_TO_STDERR that correspond to the members + .no_stdin, .git_cmd, .stdout_to_stderr of struct child_process. + The argument dir corresponds the member .dir. The argument env + corresponds to the member .env. +
+
+start_async +: +
+ Run a function asynchronously. Takes a pointer to a struct + async that specifies the details and returns a pipe FD + from which the caller reads. See below for details. +
+
+finish_async +: +
+ Wait for the completeion of an asynchronous function that was + started with start_async(). +
+

Data structures

-Environment the command runs with (e.g. GIT_DIR); +struct child_process +
+

This describes the arguments, redirections, and environment of a +command to run in a sub-process.

The caller:

+
+allocates and clears (memset(&chld, 0, sizeof(chld));) a + struct child_process variable; +
+
+
+initializes the members; +
+
+
+calls start_command(); +
+
+
+processes the data; +
+
+
+closes file descriptors (if necessary; see below); +
+
+
+calls finish_command(). +
+

The .argv member is set up as an array of string pointers (NULL +terminated), of which .argv[0] is the program name to run (usually +without a path). If the command to run is a git command, set argv[0] to +the command name without the git- prefix and set .git_cmd = 1.

The members .in, .out, .err are used to redirect stdin, stdout, +stderr as follows:

+
+Specify 0 to request no special redirection. No new file descriptor + is allocated. The child process simply inherits the channel from the + parent. +
+

+Specify -1 to have a pipe allocated; start_command() replaces -1 + by the pipe FD in the following way: +

.in: Returns the writable pipe end into which the caller writes;
+        the readable end of the pipe becomes the child's stdin.

.out, .err: Returns the readable pipe end from which the caller
+        reads; the writable end of the pipe end becomes child's
+        stdout/stderr.

The caller of start_command() must close the so returned FDs
+after it has completed reading from/writing to it!

+Specify a file descriptor > 0 to be used by the child:

.in: The FD must be readable; it becomes child's stdin.
+.out: The FD must be writable; it becomes child's stdout.
+.err > 0 is not supported.

The specified FD is closed by start_command(), even if it fails to
+run the sub-process!

-File descriptors and pipes; +Special forms of redirection are available by setting these members + to 1:

.no_stdin, .no_stdout, .no_stderr: The respective channel is
+        redirected to /dev/null.

.stdout_to_stderr: stdout of the child is redirected to the
+        parent's stderr (i.e. *not* to what .err or
+        .no_stderr specify).

To modify the environment of the sub-process, specify an array of +string pointers (NULL terminated) in .env:

-Exit status; +If the string is of the form "VAR=value", i.e. it contains = + the variable is added to the child process's environment. +
+
+
+If the string does not contain =, it names an environement + variable that will be removed from the child process's envionment. +
+

To specify a new initial working directory for the sub-process, +specify it in the .dir member.

+
+struct async

(Hannes, Dscho, Shawn)

This describes a function to run asynchronously, whose purpose is +to produce output that the caller reads.

The caller:

+
+allocates and clears (memset(&asy, 0, sizeof(asy));) a + struct async variable; +
+
+
+initializes .proc and .data; +
+
+
+calls start_async(); +
+
+
+processes the data by reading from the fd in .out; +
+
+
+closes .out; +
+
+
+calls finish_async(). +
+

The function pointer in .proc has the following signature:

int proc(int fd, void *data);

+
+fd specifies a writable file descriptor to which the function must + write the data that it produces. The function must close this + descriptor before it returns. +
+
+
+data is the value that the caller has specified in the .data member + of struct async. +
+
+
+The return value of the function is 0 on success and non-zero + on failure. If the function indicates failure, finish_async() will + report failure as well. +
+

There are serious restrictions on what the asynchronous function can do +because this facility is implemented by a pipe to a forked process on +UNIX, but by a thread in the same address space on Windows:

+
+It cannot change the program's state (global variables, environment, + etc.) in a way that the caller notices; in other words, .out is the + only communication channel to the caller. +
+
+
+It must not change the program's state that the caller of the + facility also uses. +
+

diff --git a/technical/api-run-command.txt b/technical/api-run-command.txt index 19d2f64f7..dfbf9ac5d 100644 --- a/technical/api-run-command.txt +++ b/technical/api-run-command.txt @@ -1,10 +1,171 @@ run-command API =============== -Talk about , and things like: +The run-command API offers a versatile tool to run sub-processes with +redirected input and output as well as with a modified environment +and an alternate current directory. -* Environment the command runs with (e.g. GIT_DIR); -* File descriptors and pipes; -* Exit status; +A similar API offers the capability to run a function asynchronously, +which is primarily used to capture the output that the function +produces in the caller in order to process it. -(Hannes, Dscho, Shawn) + +Functions +--------- + +`start_command`:: + + Start a sub-process. Takes a pointer to a `struct child_process` + that specifies the details and returns pipe FDs (if requested). + See below for details. + +`finish_command`:: + + Wait for the completion of a sub-process that was started with + start_command(). + +`run_command`:: + + A convenience function that encapsulates a sequence of + start_command() followed by finish_command(). Takes a pointer + to a `struct child_process` that specifies the details. + +`run_command_v_opt`, `run_command_v_opt_dir`, `run_command_v_opt_cd_env`:: + + Convenience functions that encapsulate a sequence of + start_command() followed by finish_command(). The argument argv + specifies the program and its arguments. The argument opt is zero + or more of the flags `RUN_COMMAND_NO_STDIN`, `RUN_GIT_CMD`, or + `RUN_COMMAND_STDOUT_TO_STDERR` that correspond to the members + .no_stdin, .git_cmd, .stdout_to_stderr of `struct child_process`. + The argument dir corresponds the member .dir. The argument env + corresponds to the member .env. + +`start_async`:: + + Run a function asynchronously. Takes a pointer to a `struct + async` that specifies the details and returns a pipe FD + from which the caller reads. See below for details. + +`finish_async`:: + + Wait for the completeion of an asynchronous function that was + started with start_async(). + + +Data structures +--------------- + +* `struct child_process` + +This describes the arguments, redirections, and environment of a +command to run in a sub-process. + +The caller: + +1. allocates and clears (memset(&chld, '0', sizeof(chld));) a + struct child_process variable; +2. initializes the members; +3. calls start_command(); +4. processes the data; +5. closes file descriptors (if necessary; see below); +6. calls finish_command(). + +The .argv member is set up as an array of string pointers (NULL +terminated), of which .argv[0] is the program name to run (usually +without a path). If the command to run is a git command, set argv[0] to +the command name without the 'git-' prefix and set .git_cmd = 1. + +The members .in, .out, .err are used to redirect stdin, stdout, +stderr as follows: + +. Specify 0 to request no special redirection. No new file descriptor + is allocated. The child process simply inherits the channel from the + parent. + +. Specify -1 to have a pipe allocated; start_command() replaces -1 + by the pipe FD in the following way: + + .in: Returns the writable pipe end into which the caller writes; + the readable end of the pipe becomes the child's stdin. + + .out, .err: Returns the readable pipe end from which the caller + reads; the writable end of the pipe end becomes child's + stdout/stderr. + + The caller of start_command() must close the so returned FDs + after it has completed reading from/writing to it! + +. Specify a file descriptor > 0 to be used by the child: + + .in: The FD must be readable; it becomes child's stdin. + .out: The FD must be writable; it becomes child's stdout. + .err > 0 is not supported. + + The specified FD is closed by start_command(), even if it fails to + run the sub-process! + +. Special forms of redirection are available by setting these members + to 1: + + .no_stdin, .no_stdout, .no_stderr: The respective channel is + redirected to /dev/null. + + .stdout_to_stderr: stdout of the child is redirected to the + parent's stderr (i.e. *not* to what .err or + .no_stderr specify). + +To modify the environment of the sub-process, specify an array of +string pointers (NULL terminated) in .env: + +. If the string is of the form "VAR=value", i.e. it contains '=' + the variable is added to the child process's environment. + +. If the string does not contain '=', it names an environement + variable that will be removed from the child process's envionment. + +To specify a new initial working directory for the sub-process, +specify it in the .dir member. + + +* `struct async` + +This describes a function to run asynchronously, whose purpose is +to produce output that the caller reads. + +The caller: + +1. allocates and clears (memset(&asy, '0', sizeof(asy));) a + struct async variable; +2. initializes .proc and .data; +3. calls start_async(); +4. processes the data by reading from the fd in .out; +5. closes .out; +6. calls finish_async(). + +The function pointer in .proc has the following signature: + + int proc(int fd, void *data); + +. fd specifies a writable file descriptor to which the function must + write the data that it produces. The function *must* close this + descriptor before it returns. + +. data is the value that the caller has specified in the .data member + of struct async. + +. The return value of the function is 0 on success and non-zero + on failure. If the function indicates failure, finish_async() will + report failure as well. + + +There are serious restrictions on what the asynchronous function can do +because this facility is implemented by a pipe to a forked process on +UNIX, but by a thread in the same address space on Windows: + +. It cannot change the program's state (global variables, environment, + etc.) in a way that the caller notices; in other words, .out is the + only communication channel to the caller. + +. It must not change the program's state that the caller of the + facility also uses. -- 2.26.2