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

Contents of /trunk/src/rc.h

Parent Directory Parent Directory | Revision Log Revision Log


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

  ViewVC Help
Powered by ViewVC 1.1.20