]>
Commit | Line | Data |
---|---|---|
c1189cae JK |
1 | argv-array API |
2 | ============== | |
3 | ||
4 | The argv-array API allows one to dynamically build and store | |
5 | NULL-terminated lists. An argv-array maintains the invariant that the | |
6 | `argv` member always points to a non-NULL array, and that the array is | |
7 | always NULL-terminated at the element pointed to by `argv[argc]`. This | |
8 | makes the result suitable for passing to functions expecting to receive | |
9 | argv from main(), or the link:api-run-command.html[run-command API]. | |
10 | ||
204f6d69 | 11 | The string-list API (documented in string-list.h) is similar, but cannot be |
c1189cae JK |
12 | used for these purposes; instead of storing a straight string pointer, |
13 | it contains an item structure with a `util` field that is not compatible | |
14 | with the traditional argv interface. | |
15 | ||
16 | Each `argv_array` manages its own memory. Any strings pushed into the | |
17 | array are duplicated, and all memory is freed by argv_array_clear(). | |
18 | ||
19 | Data Structures | |
20 | --------------- | |
21 | ||
22 | `struct argv_array`:: | |
23 | ||
24 | A single array. This should be initialized by assignment from | |
25 | `ARGV_ARRAY_INIT`, or by calling `argv_array_init`. The `argv` | |
26 | member contains the actual array; the `argc` member contains the | |
27 | number of elements in the array, not including the terminating | |
28 | NULL. | |
29 | ||
30 | Functions | |
31 | --------- | |
32 | ||
33 | `argv_array_init`:: | |
34 | Initialize an array. This is no different than assigning from | |
35 | `ARGV_ARRAY_INIT`. | |
36 | ||
37 | `argv_array_push`:: | |
38 | Push a copy of a string onto the end of the array. | |
39 | ||
d15bbe13 JK |
40 | `argv_array_pushl`:: |
41 | Push a list of strings onto the end of the array. The arguments | |
42 | should be a list of `const char *` strings, terminated by a NULL | |
43 | argument. | |
44 | ||
c1189cae JK |
45 | `argv_array_pushf`:: |
46 | Format a string and push it onto the end of the array. This is a | |
47 | convenience wrapper combining `strbuf_addf` and `argv_array_push`. | |
48 | ||
85b34324 PT |
49 | `argv_array_pushv`:: |
50 | Push a null-terminated array of strings onto the end of the array. | |
51 | ||
fe4a0a28 JK |
52 | `argv_array_pop`:: |
53 | Remove the final element from the array. If there are no | |
54 | elements in the array, do nothing. | |
55 | ||
c1189cae JK |
56 | `argv_array_clear`:: |
57 | Free all memory associated with the array and return it to the | |
58 | initial, empty state. | |
b992657e JK |
59 | |
60 | `argv_array_detach`:: | |
61 | Disconnect the `argv` member from the `argv_array` struct and | |
62 | return it. The caller is responsible for freeing the memory used | |
63 | by the array, and by the strings it references. After detaching, | |
64 | the `argv_array` is in a reinitialized state and can be pushed | |
65 | into again. |