]>
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 | ||
11 | The link:api-string-list.html[string-list API] is similar, but cannot be | |
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 | ||
40 | `argv_array_pushf`:: | |
41 | Format a string and push it onto the end of the array. This is a | |
42 | convenience wrapper combining `strbuf_addf` and `argv_array_push`. | |
43 | ||
44 | `argv_array_clear`:: | |
45 | Free all memory associated with the array and return it to the | |
46 | initial, empty state. |