/[baselayout]/trunk/src/rc.h
Gentoo

Contents of /trunk/src/rc.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3041 - (show annotations) (download) (as text)
Mon Oct 15 16:03:49 2007 UTC (6 years, 11 months ago) by uberlord
File MIME type: text/x-chdr
File size: 15240 byte(s)
This is probably better
1 /*!
2 * @file rc.h
3 * @brief Describes how to interface with the RC library
4 * @internal
5 *
6 * Copyright 2007 Gentoo Foundation
7 * Released under the GPLv2
8 */
9
10 #ifndef __RC_H__
11 #define __RC_H__
12
13 #ifdef __GNUC__
14 # define GCC_VERSION (__GNUC__ * 1000 + __GNUC__MINOR)
15 # if (GCC_VERSION >= 3005)
16 # define SENTINEL __attribute__ ((__sentinel__))
17 # endif
18 #endif
19 #ifndef SENTINEL
20 # define SENTINEL
21 #endif
22
23 #include <sys/types.h>
24 #include <stdbool.h>
25
26 /*! @name Reserved runlevel names */
27 #define RC_LEVEL_SYSINIT "sysinit"
28 #define RC_LEVEL_SINGLE "single"
29 #define RC_LEVEL_SHUTDOWN "shutdown"
30 #define RC_LEVEL_REBOOT "reboot"
31
32 /*! Return the current runlevel.
33 * @return the current runlevel */
34 char *rc_runlevel_get (void);
35
36 /*! Checks if the runlevel exists or not
37 * @param runlevel to check
38 * @return true if the runlevel exists, otherwise false */
39 bool rc_runlevel_exists (const char *runlevel);
40
41 /*! Return a NULL terminated list of runlevels
42 * @return a NULL terminated list of runlevels */
43 char **rc_runlevel_list (void);
44
45 /*! Set the runlevel.
46 * This just changes the stored runlevel and does not start or stop any services.
47 * @param runlevel to store */
48 bool rc_runlevel_set (const char *runlevel);
49
50 /*! Is the runlevel starting?
51 * @return true if yes, otherwise false */
52 bool rc_runlevel_starting (void);
53
54 /*! Is the runlevel stopping?
55 * @return true if yes, otherwise false */
56 bool rc_runlevel_stopping (void);
57
58 /*! @name RC
59 * A service can be given as a full path or just its name.
60 * If its just a name then we try to resolve the service to a full path.
61 * This should allow the use if local init.d directories in the future. */
62
63 /*! @brief States a service can be in */
64 typedef enum
65 {
66 /* These are actual states
67 * The service has to be in one only at all times */
68 RC_SERVICE_STOPPED = 0x0001,
69 RC_SERVICE_STARTED = 0x0002,
70 RC_SERVICE_STOPPING = 0x0004,
71 RC_SERVICE_STARTING = 0x0008,
72 RC_SERVICE_INACTIVE = 0x0010,
73
74 /* Service may or may not have been coldplugged */
75 RC_SERVICE_COLDPLUGGED = 0x0100,
76
77 /* Optional states service could also be in */
78 RC_SERVICE_FAILED = 0x0200,
79 RC_SERVICE_SCHEDULED = 0x0400,
80 RC_SERVICE_WASINACTIVE = 0x0800
81 } rc_service_state_t;
82
83 /*! Add the service to the runlevel
84 * @param runlevel to add to
85 * @param service to add
86 * @return true if successful, otherwise false */
87 bool rc_service_add (const char *runlevel, const char *service);
88
89 /*! Remove the service from the runlevel
90 * @param runlevel to remove from
91 * @param service to remove
92 * @return true if sucessful, otherwise false */
93 bool rc_service_delete (const char *runlevel, const char *service);
94
95 /*! Save the arguments to find a running daemon
96 * @param service to save arguments for
97 * @param exec that we started
98 * @param name of the process (optional)
99 * @param pidfile of the process (optional)
100 * @param started if true, add the arguments otherwise remove existing matching arguments */
101 bool rc_service_daemon_set (const char *service, const char *exec,
102 const char *name, const char *pidfile,
103 bool started);
104
105 /*! Returns a description of what the service and/or option does.
106 * @param service to check
107 * @param option to check (if NULL, service description)
108 * @return a newly allocated pointer to the description */
109 char *rc_service_description (const char *service, const char *option);
110
111 /*! Checks if a service exists or not.
112 * @param service to check
113 * @return true if service exists, otherwise false */
114 bool rc_service_exists (const char *service);
115
116 /*! Checks if a service is in a runlevel
117 * @param service to check
118 * @param runlevel it should be in
119 * @return true if service is in the runlevel, otherwise false */
120 bool rc_service_in_runlevel (const char *service, const char *runlevel);
121
122 /*! Marks the service state
123 * @param service to mark
124 * @param state service should be in
125 * @return true if service state change was successful, otherwise false */
126 bool rc_service_mark (const char *service, rc_service_state_t state);
127
128 /*! Lists the extra options a service has
129 * @param service to load the options from
130 * @return NULL terminated string list of options */
131 char **rc_service_options (const char *service);
132
133 /*! Check if the service is allowed to be hot/cold plugged
134 * @param service to check
135 * @return true if allowed, otherwise false */
136 bool rc_service_plugable (char *service);
137
138 /*! Resolves a service name to its full path.
139 * @param service to check
140 * @return pointer to full path of service */
141 char *rc_service_resolve (const char *service);
142
143 /*! Schedule a service to be started when another service starts
144 * @param service that starts the scheduled service when started
145 * @param service_to_start service that will be started */
146 bool rc_service_schedule_start (const char *service,
147 const char *service_to_start);
148 /*! Return a NULL terminated list of services that are scheduled to start
149 * when the given service has started
150 * @param service to check
151 * @return NULL terminated list of services scheduled to start */
152 char **rc_services_scheduled_by (const char *service);
153
154 /*! Clear the list of services scheduled to be started by this service
155 * @param service to clear
156 * @return true if no errors, otherwise false */
157 bool rc_service_schedule_clear (const char *service);
158
159 /*! Checks if a service in in a state
160 * @param service to check
161 * @return state of the service */
162 rc_service_state_t rc_service_state (const char *service);
163
164 /*! Start a service
165 * @param service to start
166 * @return pid of the service starting process */
167 pid_t rc_service_start (const char *service);
168
169 /*! Stop a service
170 * @param service to stop
171 * @return pid of service stopping process */
172 pid_t rc_service_stop (const char *service);
173
174 /*! Check if the service started the daemon
175 * @param service to check
176 * @param exec to check
177 * @param indx of the daemon (optional - 1st daemon, 2nd daemon, etc)
178 * @return true if started by this service, otherwise false */
179 bool rc_service_started_daemon (const char *service, const char *exec,
180 int indx);
181
182 /*! Return a saved value for a service
183 * @param service to check
184 * @param option to load
185 * @return saved value */
186 char *rc_service_value_get (const char *service, const char *option);
187
188 /*! Save a persistent value for a service
189 * @param service to save for
190 * @param option to save
191 * @param value of the option
192 * @return true if saved, otherwise false */
193 bool rc_service_value_set (const char *service, const char *option,
194 const char *value);
195
196 /*! Wait for a service to finish
197 * @param service to wait for
198 * @return true if service finished before timeout, otherwise false */
199 bool rc_service_wait (const char *service);
200
201 /*! List the services in a runlevel
202 * @param runlevel to list
203 * @return NULL terminated list of services */
204 char **rc_services_in_runlevel (const char *runlevel);
205
206 /*! List the services in a state
207 * @param state to list
208 * @return NULL terminated list of services */
209 char **rc_services_in_state (rc_service_state_t state);
210
211 /*! List the services shceduled to start when this one does
212 * @param service to check
213 * @return NULL terminated list of services */
214 char **rc_services_scheduled (const char *service);
215
216 /*! Checks that all daemons started with start-stop-daemon by the service
217 * are still running.
218 * @param service to check
219 * @return true if all daemons started are still running, otherwise false */
220 bool rc_service_daemons_crashed (const char *service);
221
222 /*! @name Dependency options
223 * These options can change the services found by the rc_get_depinfo and
224 * rc_get_depends functions. */
225 /*! Trace provided services */
226 #define RC_DEP_TRACE 0x01
227 /*! Only use services added to runlevels */
228 #define RC_DEP_STRICT 0x02
229 /*! Runlevel is starting */
230 #define RC_DEP_START 0x04
231 /*! Runlevel is stopping */
232 #define RC_DEP_STOP 0x08
233
234 /*! @name Dependencies
235 * We analyse each init script and cache the resultant dependency tree.
236 * This tree can be accessed using the below functions. */
237
238 #ifndef _IN_LIBRC
239 /* Handles to internal structures */
240 typedef void *rc_depinfo_t;
241 #endif
242
243 /*! Update the cached dependency tree if it's older than any init script,
244 * its configuration file or an external configuration file the init script
245 * has specified.
246 * @return true if successful, otherwise false */
247 bool rc_deptree_update (void);
248
249 /*! Check if the cached dependency tree is older than any init script,
250 * its configuration file or an external configuration file the init script
251 * has specified.
252 * @return true if it needs updating, otherwise false */
253 bool rc_deptree_update_needed (void);
254
255 /*! Load the cached dependency tree and return a pointer to it.
256 * This pointer should be freed with rc_deptree_free when done.
257 * @return pointer to the dependency tree */
258 rc_depinfo_t *rc_deptree_load (void);
259
260 /*! List all the services in order that the given services have
261 * for the given types and options.
262 * @param deptree to search
263 * @param types to use (ineed, iuse, etc)
264 * @param services to check
265 * @param options to pass
266 * @return NULL terminated list of services in order */
267 char **rc_deptree_depends (rc_depinfo_t *deptree, const char **types,
268 const char **services, const char *runlevel,
269 int options);
270
271 /*! List all the services that should be stoppned and then started, in order,
272 * for the given runlevel, including sysinit and boot services where
273 * approriate.
274 * @param deptree to search
275 * @param runlevel to change into
276 * @param options to pass
277 * @return NULL terminated list of services in order */
278 char **rc_deptree_order (rc_depinfo_t *deptree, const char *runlevel,
279 int options);
280
281 /*! Free a deptree and its information
282 * @param deptree to free */
283 void rc_deptree_free (rc_depinfo_t *deptree);
284
285 /*! @name Plugins
286 * For each plugin loaded we will call rc_plugin_hook with the below
287 * enum and either the runlevel name or service name.
288 *
289 * Plugins are called when rc does something. This does not indicate an
290 * end result and the plugin should use the above functions to query things
291 * like service status.
292 *
293 * The service hooks have extra ones - now and done. This is because after
294 * start_in we may start other services before we start the service in
295 * question. now shows we really will start the service now and done shows
296 * when we have done it as may start scheduled services at this point. */
297 /*! Points at which a plugin can hook into RC */
298 typedef enum
299 {
300 RC_HOOK_RUNLEVEL_STOP_IN = 1,
301 RC_HOOK_RUNLEVEL_STOP_OUT = 4,
302 RC_HOOK_RUNLEVEL_START_IN = 5,
303 RC_HOOK_RUNLEVEL_START_OUT = 8,
304 /*! We send the abort if an init script requests we abort and drop
305 * into single user mode if system not fully booted */
306 RC_HOOK_ABORT = 99,
307 RC_HOOK_SERVICE_STOP_IN = 101,
308 RC_HOOK_SERVICE_STOP_NOW = 102,
309 RC_HOOK_SERVICE_STOP_DONE = 103,
310 RC_HOOK_SERVICE_STOP_OUT = 104,
311 RC_HOOK_SERVICE_START_IN = 105,
312 RC_HOOK_SERVICE_START_NOW = 106,
313 RC_HOOK_SERVICE_START_DONE = 107,
314 RC_HOOK_SERVICE_START_OUT = 108
315 } rc_hook_t;
316
317 /*! Plugin entry point
318 * @param hook point
319 * @param name of runlevel or service
320 * @return 0 for success otherwise -1 */
321 int rc_plugin_hook (rc_hook_t hook, const char *name);
322
323 /*! Plugins should write FOO=BAR to this fd to set any environment
324 * variables they wish. Variables should be separated by NULLs. */
325 extern FILE *rc_environ_fd;
326
327 /*! @name Configuration
328 * These functions help to deal with shell based configuration files */
329 /*! Return a NULL terminated list of non comment lines from a file. */
330 char **rc_config_list (const char *file);
331
332 /*! Return a NULL terminated list of key=value lines from a file. */
333 char **rc_config_load (const char *file);
334
335 /*! Return the value of the entry from a key=value list. */
336 char *rc_config_value (char **list, const char *entry);
337
338 /*! Check if an environment variable is a boolean and return it's value.
339 * If variable is not a boolean then we set errno to be ENOENT when it does
340 * not exist or EINVAL if it's not a boolean.
341 * @param variable to check
342 * @return true if it matches true, yes or 1, false if otherwise. */
343 bool rc_env_bool (const char *variable);
344
345 /*! @name String List functions
346 * Handy functions for dealing with string arrays of char **.
347 * It's safe to assume that any function here that uses char ** is a string
348 * list that can be manipulated with the below functions. Every string list
349 * should be released with a call to rc_strlist_free. */
350
351 /*! Duplicate the item, add it to end of the list and return a pointer to it.
352 * @param list to add the item too
353 * @param item to add.
354 * @return pointer to newly added item */
355 char *rc_strlist_add (char ***list, const char *item);
356
357 /*! If the item does not exist in the list, duplicate it, add it to the
358 * list and then return a pointer to it.
359 * @param list to add the item too
360 * @param item to add.
361 * @return pointer to newly added item */
362 char *rc_strlist_addu (char ***list, const char *item);
363
364 /*! Duplicate the item, add it to the list at the point based on locale and
365 * then return a pointer to it.
366 * @param list to add the item too
367 * @param item to add.
368 * @return pointer to newly added item */
369 char *rc_strlist_addsort (char ***list, const char *item);
370
371 /*! Duplicate the item, add it to the list at the point based on C locale and
372 * then return a pointer to it.
373 * @param list to add the item too
374 * @param item to add.
375 * @return pointer to newly added item */
376 char *rc_strlist_addsortc (char ***list, const char *item);
377
378 /*! If the item does not exist in the list, duplicate it, add it to the
379 * list based on locale and then return a pointer to it.
380 * @param list to add the item too
381 * @param item to add.
382 * @return pointer to newly added item */
383 char *rc_strlist_addsortu (char ***list, const char *item);
384
385 /*! Free the item and remove it from the list. Return 0 on success otherwise -1.
386 * @param list to add the item too
387 * @param item to add.
388 * @return true on success, otherwise false */
389 bool rc_strlist_delete (char ***list, const char *item);
390
391 /*! Moves the contents of list2 onto list1, so list2 is effectively emptied.
392 * Returns a pointer to the last item on the new list.
393 * @param list1 to append to
394 * @param list2 to move from
395 * @return pointer to the last item on the list */
396 char *rc_strlist_join (char ***list1, char **list2);
397
398 /*! Reverses the contents of the list.
399 * @param list to reverse */
400 void rc_strlist_reverse (char **list);
401
402 /*! Frees each item on the list and the list itself.
403 * @param list to free */
404 void rc_strlist_free (char **list);
405
406 /*! Concatenate paths adding '/' if needed. The resultant pointer should be
407 * freed when finished with.
408 * @param path1 starting path
409 * @param paths NULL terminated list of paths to add
410 * @return pointer to the new path */
411 char *rc_strcatpaths (const char *path1, const char *paths, ...) SENTINEL;
412
413 /*! Find processes based on criteria.
414 * All of these are optional.
415 * pid overrides anything else.
416 * If both exec and cmd are given then we ignore exec.
417 * @param exec to check for
418 * @param cmd to check for
419 * @param uid to check for
420 * @param pid to check for
421 * @return NULL terminated list of pids */
422 pid_t *rc_find_pids (const char *exec, const char *cmd,
423 uid_t uid, pid_t pid);
424
425 #endif

  ViewVC Help
Powered by ViewVC 1.1.20