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

Contents of /trunk/src/rc.h

Parent Directory Parent Directory | Revision Log Revision Log


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

  ViewVC Help
Powered by ViewVC 1.1.20