1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
.. _processes:
*********
Processes
*********
.. highlight:: c
::
#include <libcork/os.h>
The functions in this section let you interact with the current running process.
Cleanup functions
~~~~~~~~~~~~~~~~~
Often you will need to perform some cleanup tasks whenever the current process
terminates normally. The functions in this section let you do that.
.. function:: void cork_cleanup_at_exit(int priority, cork_cleanup_function function)
void cork_cleanup_at_exit_named(const char \*name, int priority, cork_cleanup_function function)
Register a *function* that should be called when the current process
terminates. When multiple functions are registered, the order in which they
are called is determined by their *priority* values --- functions with lower
priorities will be called first. If any functions have the same priority
value, there is no guarantee about the order in which they will be called.
All cleanup functions must conform to the following signature:
.. type:: void (\*cork_cleanup_function)(void)
The ``_named`` variant lets you provide an explicit name for the cleanup
function, which currently is only used when printing out debug messages. The
plain variant automatically detects the name of *function*, so that you don't
have to provide it explicitly.
.. _env:
Environment variables
~~~~~~~~~~~~~~~~~~~~~
.. type:: struct cork_env
A collection of environment variables that can be passed to subprocesses.
.. function:: struct cork_env \*cork_env_new(void)
Create a new, empty collection of environment variables.
.. function:: struct cork_env \*cork_env_clone_current(void)
Create a new :c:type:`cork_env` containing all of the environment variables
in the current process's environment list.
.. function:: void cork_env_free(struct cork_env \*env)
Free a collection of environment variables.
.. function:: const char \*cork_env_get(struct cork_env \*env, const char \*name)
Return the value of the environment variable with the given *name*. If there
is no variable with that name, return ``NULL``.
If *env* is ``NULL``, then the variable is retrieved from the current process
environment; otherwise, it is retrieved from *env*.
.. function:: void cork_env_add(struct cork_env \*env, const char \*name, const char \*value)
void cork_env_add_printf(struct cork_env \*env, const char \*name, const char \*format, ...)
void cork_env_add_vprintf(struct cork_env \*env, const char \*name, const char \*format, va_list args)
Add a new environment variable with the given *name* and *value*. If there
is already a variable with that name, it is overwritten. We make a copy of
both *name* and *variable*, so it is safe to pass in temporary or reusable
strings for either. The ``printf`` and ``vprintf`` variants construct the
new variable's value from a ``printf``-like format string.
If *env* is ``NULL``, then the new variable is added to the current process
environment; otherwise, it is added to *env*.
.. function:: void cork_env_remove(struct cork_env \*env, const char \*name)
Remove the environment variable with the given *name*, if it exists. If
there isn't any variable with that name, do nothing.
If *env* is ``NULL``, then the variable is removed from the current process
environment; otherwise, it is removed from *env*.
.. function:: void cork_env_replace_current(struct cork_env \*env)
Replace the current process's environment list with the contents of *env*.
.. _exec:
Executing another program
~~~~~~~~~~~~~~~~~~~~~~~~~
.. type:: struct cork_exec
A specification for executing another program.
.. function:: struct cork_exec \*cork_exec_new(const char \*program)
struct cork_exec \*cork_exec_new_with_params(const char \*program, ...)
struct cork_exec \*cork_exec_new_with_param_array(const char \*program, char \* const \*params)
Create a new specification for executing *program*. *program* must either be
an absolute path to an executable on the local filesystem, or the name of an
executable that should be found in the current ``PATH``.
The first variant creates a specification that initially doesn't contain any
parameters to pass into the new program. The second variant allows you to
pass in each argument as a separate parameter; you must ensure that you
terminate the list of parameters with a ``NULL`` pointer. The third variant
allows you to pass in a ``NULL``-terminated array of strings to use as an
initial parameter list. For all three variants, you can add additional
parameters before executing the new program via the :c:func:`cork_add_param`
function.
.. note::
Most programs will expect the first parameter to be the name of the
program being executed. The :c:func:`cork_exec_new_with_params` function
will automatically fill in this first parameter for you. The other
constructor functions do not; when using them, it is your responsibility
to provide this parameter, just like any other parameters to pass into the
program.
This function does not actually execute the program; that is handled by the
:c:func:`cork_exec_run` function.
.. function:: void cork_exec_free(struct cork_exec \*exec)
Free an execution specification. You normally won't need to call this
function; normally you'll replace the current process with the new program
(by calling :c:func:`cork_exec_run`), which means you won't have a chance to
free the specification object.
.. function:: const char \*cork_exec_description(struct cork_exec \*exec)
Return a string description of the program described by an execution
specification.
.. function:: void cork_exec_add_param(struct cork_exec \*exec, const char \*param)
Add a parameter to the parameter list that will be passed into the new
program.
.. function:: void cork_exec_set_env(struct cork_exec \*exec, struct cork_env \*env)
Provide a set of environment variables that will be passed into the new
program. The subprocess's environment will contain only those variables
defined in *env*. You can use the :c:func:`cork_env_clone_current` function
to create a copy of the current process's environment, to use it as a base to
add new variables or remove unsafe variables. We will take control of *env*,
so you must **not** call :c:func:`cork_env_free` to free the environment
yourself.
If you don't call this function for a specification object, the new
program will use the same environment as the calling process.
.. function:: void cork_exec_set_cwd(struct cork_exec \*exec, const char \directory)
Change the working directory that the new program will be called from. If
you don't call this function for a specification object, the new program will
be executed in the same working directory as the calling process.
.. function:: const char \*cork_exec_program(struct cork_exec \*exec)
size_t \*cork_exec_param_count(struct cork_exec \*exec)
const char \*cork_exec_param(struct cork_exec \*exec, size_t index)
struct cork_env \*cork_exec_env(struct cork_exec \*exec)
const char \*cork_exec_cwd(struct cork_exec \*exec)
Accessor functions that allow you to retrieve the contents of an execution
specification. The :c:func:`cork_exec_env` and :c:func:`cork_exec_cwd`
functions might return ``NULL``, if there isn't an environment or working
directory specified.
.. function:: int cork_exec_run(struct cork_exec \*exec)
Execute the program specified by *exec*, replacing the current process.
If we can successfully start the new program, this function will not return.
If there are any errors starting the program, this function will return an
error condition.
|
