rc.h File Reference

Describes how to interface with the RC library. More...

#include <sys/types.h>
#include <stdbool.h>
#include <stdio.h>

Go to the source code of this file.

Classes

struct  rc_deptype
struct  rc_depinfo

RC

A service can be given as a full path or just its name. If its just a name then we try to resolve the service to a full path. This should allow the use if local init.d directories in the future.

enum  rc_service_state_t {
  rc_service_started, rc_service_stopped, rc_service_starting, rc_service_stopping,
  rc_service_inactive, rc_service_wasinactive, rc_service_coldplugged, rc_service_failed,
  rc_service_scheduled, rc_service_crashed
}
 States a service can be in.
char * rc_resolve_service (const char *service)
bool rc_service_exists (const char *service)
char ** rc_service_options (const char *service)
char * rc_service_description (const char *service, const char *option)
bool rc_service_in_runlevel (const char *service, const char *runlevel)
bool rc_service_state (const char *service, rc_service_state_t state)
bool rc_mark_service (const char *service, rc_service_state_t state)
pid_t rc_stop_service (const char *service)
pid_t rc_start_service (const char *service)
int rc_waitpid (pid_t pid)
void rc_schedule_start_service (const char *service, const char *service_to_start)
char ** rc_services_scheduled_by (const char *service)
void rc_schedule_clear (const char *service)
bool rc_wait_service (const char *service)
char * rc_get_service_option (const char *service, const char *option)
bool rc_set_service_option (const char *service, const char *option, const char *value)
void rc_set_service_daemon (const char *service, const char *exec, const char *name, const char *pidfile, bool started)
bool rc_service_started_daemon (const char *service, const char *exec, int indx)
bool rc_allow_plug (char *service)
char * rc_get_runlevel (void)
void rc_set_runlevel (const char *runlevel)
bool rc_runlevel_exists (const char *runlevel)
char ** rc_get_runlevels (void)
bool rc_runlevel_starting (void)
bool rc_runlevel_stopping (void)
bool rc_service_add (const char *runlevel, const char *service)
bool rc_service_delete (const char *runlevel, const char *service)
char ** rc_services_in_runlevel (const char *runlevel)
char ** rc_services_in_state (rc_service_state_t state)
char ** rc_services_scheduled (const char *service)
pid_t * rc_find_pids (const char *exec, const char *cmd, uid_t uid, pid_t pid)
bool rc_service_daemons_crashed (const char *service)

Plugins

For each plugin loaded we will call rc_plugin_hook with the below enum and either the runlevel name or service name.

Plugins are called when rc does something. This does not indicate an end result and the plugin should use the above functions to query things like service status.

The service hooks have extra ones - now and done. This is because after start_in we may start other services before we start the service in question. now shows we really will start the service now and done shows when we have done it as may start scheduled services at this point.

enum  rc_hook_t {
  rc_hook_runlevel_stop_in = 1, rc_hook_runlevel_stop_out = 4, rc_hook_runlevel_start_in = 5, rc_hook_runlevel_start_out = 8,
  rc_hook_abort = 99, rc_hook_service_stop_in = 101, rc_hook_service_stop_now, rc_hook_service_stop_done,
  rc_hook_service_stop_out, rc_hook_service_start_in, rc_hook_service_start_now, rc_hook_service_start_done,
  rc_hook_service_start_out
}
FILE * rc_environ_fd
int rc_plugin_hook (rc_hook_t hook, const char *name)

Dependencies

We analyse each init script and cache the resultant dependency tree. This tree can be accessed using the below structures and functions.

typedef struct rc_deptype rc_deptype_t
typedef struct rc_depinfo rc_depinfo_t
int rc_update_deptree (bool force)
rc_depinfo_trc_load_deptree (void)
rc_depinfo_trc_get_depinfo (rc_depinfo_t *deptree, const char *service)
rc_deptype_trc_get_deptype (rc_depinfo_t *depinfo, const char *type)
char ** rc_get_depends (rc_depinfo_t *deptree, char **types, char **services, const char *runlevel, int options)
char ** rc_order_services (rc_depinfo_t *deptree, const char *runlevel, int options)
void rc_free_deptree (rc_depinfo_t *deptree)

Defines

Reserved runlevel names


#define RC_LEVEL_SYSINIT   "sysinit"
#define RC_LEVEL_SINGLE   "single"
#define RC_LEVEL_SHUTDOWN   "shutdown"
#define RC_LEVEL_REBOOT   "reboot"
rc_ls_dir options


#define RC_LS_INITD   0x01
 Ensure that an init.d service exists for each file returned.
Dependency options
These options can change the services found by the rc_get_depinfo and rc_get_depends functions.

#define RC_DEP_TRACE   0x01
#define RC_DEP_STRICT   0x02
#define RC_DEP_START   0x04
#define RC_DEP_STOP   0x08

Functions

Memory Allocation
Ensure that if we cannot allocate the memory then we exit

void * rc_xmalloc (size_t size)
void * rc_xrealloc (void *ptr, size_t size)
char * rc_xstrdup (const char *str)
Utility
Although not RC specific functions, they are used by the supporting applications

char * rc_strcatpaths (const char *path1, const char *paths,...)
bool rc_is_env (const char *variable, const char *value)
bool rc_exists (const char *pathname)
bool rc_is_file (const char *pathname)
bool rc_is_link (const char *pathname)
bool rc_is_dir (const char *pathname)
bool rc_is_exec (const char *pathname)
char ** rc_ls_dir (const char *dir, int options)
bool rc_rm_dir (const char *pathname, bool top)
Configuration


char ** rc_get_list (const char *file)
char ** rc_get_config (const char *file)
char * rc_get_config_entry (char **list, const char *entry)
char ** rc_filter_env (void)
char ** rc_make_env (void)
String List functions
Handy functions for dealing with string arrays of char **. It's safe to assume that any function here that uses char ** is a string list that can be manipulated with the below functions. Every string list should be released with a call to rc_strlist_free.

char * rc_strlist_add (char ***list, const char *item)
char * rc_strlist_addu (char ***list, const char *item)
char * rc_strlist_addsort (char ***list, const char *item)
char * rc_strlist_addsortc (char ***list, const char *item)
char * rc_strlist_addsortu (char ***list, const char *item)
int rc_strlist_delete (char ***list, const char *item)
char * rc_strlist_join (char ***list1, char **list2)
void rc_strlist_reverse (char **list)
void rc_strlist_free (char **list)


Detailed Description

Describes how to interface with the RC library.


Define Documentation

#define RC_DEP_START   0x04

Runlevel is starting

#define RC_DEP_STOP   0x08

Runlevel is stopping

#define RC_DEP_STRICT   0x02

Only use services added to runlevels

#define RC_DEP_TRACE   0x01

Trace provided services


Typedef Documentation

typedef struct rc_depinfo rc_depinfo_t

Singly linked list of services and their dependencies

typedef struct rc_deptype rc_deptype_t

Singly linked list of dependency types that list the services the type is for


Enumeration Type Documentation

enum rc_hook_t

Points at which a plugin can hook into RC

Enumerator:
rc_hook_abort  We send the abort if an init script requests we abort and drop into single user mode if system not fully booted


Function Documentation

bool rc_allow_plug ( char *  service  ) 

Check if the service is allowed to be hot/cold plugged

Parameters:
service to check
Returns:
true if allowed, otherwise false

bool rc_exists ( const char *  pathname  ) 

Check if the file exists or not

Parameters:
pathname to check
Returns:
true if it exists, otherwise false

char** rc_filter_env ( void   ) 

Return a NULL terminated string list of variables allowed through from the current environemnt.

pid_t* rc_find_pids ( const char *  exec,
const char *  cmd,
uid_t  uid,
pid_t  pid 
)

Find processes based on criteria. All of these are optional. pid overrides anything else. If both exec and cmd are given then we ignore exec.

Parameters:
exec to check for
cmd to check for
uid to check for
pid to check for
Returns:
NULL terminated list of pids

void rc_free_deptree ( rc_depinfo_t deptree  ) 

Free a deptree and its information

Parameters:
deptree to free

char** rc_get_config ( const char *  file  ) 

Return a NULL terminated list of key=value lines from a file.

char* rc_get_config_entry ( char **  list,
const char *  entry 
)

Return the value of the entry from a key=value list.

rc_depinfo_t* rc_get_depinfo ( rc_depinfo_t deptree,
const char *  service 
)

Get a services depedency information from a loaded tree

Parameters:
deptree to search
service to find
Returns:
service dependency information

rc_deptype_t* rc_get_deptype ( rc_depinfo_t depinfo,
const char *  type 
)

Get a depenency type from the service dependency information

Parameters:
depinfo service dependency to search
type to find
Returns:
service dependency type information

char** rc_get_list ( const char *  file  ) 

Return a NULL terminated list of non comment lines from a file.

char* rc_get_runlevel ( void   ) 

Return the current runlevel.

Returns:
the current runlevel

char** rc_get_runlevels ( void   ) 

Return a NULL terminated list of runlevels

Returns:
a NULL terminated list of runlevels

char* rc_get_service_option ( const char *  service,
const char *  option 
)

Return a saved value for a service

Parameters:
service to check
option to load
Returns:
saved value

bool rc_is_dir ( const char *  pathname  ) 

Check if the file is a directory or not

Parameters:
pathname to check
Returns:
true if it's a directory, otherwise false

bool rc_is_env ( const char *  variable,
const char *  value 
)

Check if an environment variable matches the given value

Parameters:
variable to check
value it should be
Returns:
true if it matches

bool rc_is_exec ( const char *  pathname  ) 

Check if the file is marked executable or not

Parameters:
pathname to check
Returns:
true if it's marked executable, otherwise false

bool rc_is_file ( const char *  pathname  ) 

Check if the file is a real file

Parameters:
pathname to check
Returns:
true if it's a real file, otherwise false

bool rc_is_link ( const char *  pathname  ) 

Check if the file is a symbolic link or not

Parameters:
pathname to check
Returns:
true if it's a symbolic link, otherwise false

rc_depinfo_t* rc_load_deptree ( void   ) 

Load the cached dependency tree and return a pointer to it. This pointer should be freed with rc_free_deptree when done.

Returns:
pointer to the dependency tree

char** rc_ls_dir ( const char *  dir,
int  options 
)

Return a NULL terminted sorted list of the contents of the directory

Parameters:
dir to list
options any options to apply
Returns:
NULL terminated list

char** rc_make_env ( void   ) 

Return a NULL terminated string list of enviroment variables made from our configuration files.

bool rc_mark_service ( const char *  service,
rc_service_state_t  state 
)

Marks the service state

Parameters:
service to mark
state service should be in
Returns:
true if service state change was successful, otherwise false

char** rc_order_services ( rc_depinfo_t deptree,
const char *  runlevel,
int  options 
)

List all the services that should be stoppned and then started, in order, for the given runlevel, including sysinit and boot services where approriate.

Parameters:
deptree to search
runlevel to change into
options to pass
Returns:
NULL terminated list of services in order

int rc_plugin_hook ( rc_hook_t  hook,
const char *  name 
)

Plugin entry point

Parameters:
hook point
name of runlevel or service
Returns:
0 for success otherwise -1

char* rc_resolve_service ( const char *  service  ) 

Resolves a service name to its full path.

Parameters:
service to check
Returns:
pointer to full path of service

bool rc_rm_dir ( const char *  pathname,
bool  top 
)

Remove a directory

Parameters:
pathname to remove
top remove the top level directory too
Returns:
true if successful, otherwise false

bool rc_runlevel_exists ( const char *  runlevel  ) 

Checks if the runlevel exists or not

Parameters:
runlevel to check
Returns:
true if the runlevel exists, otherwise false

bool rc_runlevel_starting ( void   ) 

Is the runlevel starting?

Returns:
true if yes, otherwise false

bool rc_runlevel_stopping ( void   ) 

Is the runlevel stopping?

Returns:
true if yes, otherwise false

void rc_schedule_clear ( const char *  service  ) 

Clear the list of services scheduled to be started by this service

Parameters:
service to clear

void rc_schedule_start_service ( const char *  service,
const char *  service_to_start 
)

Schedule a service to be started when another service starts

Parameters:
service that starts the scheduled service when started
service_to_start service that will be started

bool rc_service_add ( const char *  runlevel,
const char *  service 
)

Add the service to the runlevel

Parameters:
runlevel to add to
service to add
Returns:
true if successful, otherwise false

bool rc_service_daemons_crashed ( const char *  service  ) 

Checks that all daemons started with start-stop-daemon by the service are still running.

Parameters:
service to check
Returns:
true if all daemons started are still running, otherwise false

bool rc_service_delete ( const char *  runlevel,
const char *  service 
)

Remove the service from the runlevel

Parameters:
runlevel to remove from
service to remove
Returns:
true if sucessful, otherwise false

char* rc_service_description ( const char *  service,
const char *  option 
)

Returns a description of what the service and/or option does.

Parameters:
service to check
option to check (if NULL, service description)
Returns:
a newly allocated pointer to the description

bool rc_service_exists ( const char *  service  ) 

Checks if a service exists or not.

Parameters:
service to check
Returns:
true if service exists, otherwise false

bool rc_service_in_runlevel ( const char *  service,
const char *  runlevel 
)

Checks if a service is in a runlevel

Parameters:
service to check
runlevel it should be in
Returns:
true if service is in the runlevel, otherwise false

char** rc_service_options ( const char *  service  ) 

Lists the extra options a service has

Parameters:
service to load the options from
Returns:
NULL terminated string list of options

bool rc_service_started_daemon ( const char *  service,
const char *  exec,
int  indx 
)

Check if the service started the daemon

Parameters:
service to check
exec to check
indx of the daemon (optional - 1st daemon, 2nd daemon, etc)
Returns:
true if started by this service, otherwise false

bool rc_service_state ( const char *  service,
rc_service_state_t  state 
)

Checks if a service in in a state

Parameters:
service to check
state service should be in
Returns:
true if service is in the requested state, otherwise false

char** rc_services_in_runlevel ( const char *  runlevel  ) 

List the services in a runlevel

Parameters:
runlevel to list
Returns:
NULL terminated list of services

char** rc_services_in_state ( rc_service_state_t  state  ) 

List the services in a state

Parameters:
state to list
Returns:
NULL terminated list of services

char** rc_services_scheduled ( const char *  service  ) 

List the services shceduled to start when this one does

Parameters:
service to check
Returns:
NULL terminated list of services

char** rc_services_scheduled_by ( const char *  service  ) 

Return a NULL terminated list of services that are scheduled to start when the given service has started

Parameters:
service to check
Returns:
NULL terminated list of services scheduled to start

void rc_set_runlevel ( const char *  runlevel  ) 

Set the runlevel. This just changes the stored runlevel and does not start or stop any services.

Parameters:
runlevel to store

void rc_set_service_daemon ( const char *  service,
const char *  exec,
const char *  name,
const char *  pidfile,
bool  started 
)

Save the arguments to find a running daemon

Parameters:
service to save arguments for
exec that we started
name of the process (optional)
pidfile of the process (optional)
started if true, add the arguments otherwise remove existing matching arguments

bool rc_set_service_option ( const char *  service,
const char *  option,
const char *  value 
)

Save a persistent value for a service

Parameters:
service to save for
option to save
value of the option
Returns:
true if saved, otherwise false

pid_t rc_start_service ( const char *  service  ) 

Start a service

Parameters:
service to start
Returns:
pid of the service starting process

pid_t rc_stop_service ( const char *  service  ) 

Stop a service

Parameters:
service to stop
Returns:
pid of service stopping process

char* rc_strcatpaths ( const char *  path1,
const char *  paths,
  ... 
)

Concatenate paths adding '/' if needed. The resultant pointer should be freed when finished with.

Parameters:
path1 starting path
paths NULL terminated list of paths to add
Returns:
pointer to the new path

char* rc_strlist_add ( char ***  list,
const char *  item 
)

Duplicate the item, add it to end of the list and return a pointer to it.

Parameters:
list to add the item too
item to add.
Returns:
pointer to newly added item

char* rc_strlist_addsort ( char ***  list,
const char *  item 
)

Duplicate the item, add it to the list at the point based on locale and then return a pointer to it.

Parameters:
list to add the item too
item to add.
Returns:
pointer to newly added item

char* rc_strlist_addsortc ( char ***  list,
const char *  item 
)

Duplicate the item, add it to the list at the point based on C locale and then return a pointer to it.

Parameters:
list to add the item too
item to add.
Returns:
pointer to newly added item

char* rc_strlist_addsortu ( char ***  list,
const char *  item 
)

If the item does not exist in the list, duplicate it, add it to the list based on locale and then return a pointer to it.

Parameters:
list to add the item too
item to add.
Returns:
pointer to newly added item

char* rc_strlist_addu ( char ***  list,
const char *  item 
)

If the item does not exist in the list, duplicate it, add it to the list and then return a pointer to it.

Parameters:
list to add the item too
item to add.
Returns:
pointer to newly added item

int rc_strlist_delete ( char ***  list,
const char *  item 
)

Free the item and remove it from the list. Return 0 on success otherwise -1.

Parameters:
list to add the item too
item to add.
Returns:
pointer to newly added item

void rc_strlist_free ( char **  list  ) 

Frees each item on the list and the list itself.

Parameters:
list to free

char* rc_strlist_join ( char ***  list1,
char **  list2 
)

Moves the contents of list2 onto list1, so list2 is effectively emptied. Returns a pointer to the last item on the new list.

Parameters:
list1 to append to
list2 to move from
Returns:
pointer to the last item on the list

void rc_strlist_reverse ( char **  list  ) 

Reverses the contents of the list.

Parameters:
list to reverse

int rc_update_deptree ( bool  force  ) 

Update the cached dependency tree if it's older than any init script, its configuration file or an external configuration file the init script has specified.

Parameters:
force an update
Returns:
0 if successful, otherwise -1

bool rc_wait_service ( const char *  service  ) 

Wait for a service to finish

Parameters:
service to wait for
Returns:
true if service finished before timeout, otherwise false

int rc_waitpid ( pid_t  pid  ) 

Wait for a process to finish

Parameters:
pid to wait for
Returns:
exit status of the process

void* rc_xmalloc ( size_t  size  ) 

Allocate a block of memory

Parameters:
size of memory to allocate
Returns:
pointer to memory

void* rc_xrealloc ( void *  ptr,
size_t  size 
)

Re-size a block of memory

Parameters:
ptr to the block of memory to re-size
size memory should be
Returns:
pointer to memory block

char* rc_xstrdup ( const char *  str  ) 

Duplicate a NULL terminated string

Parameters:
str to duplicate
Returns:
pointer to the new string


Variable Documentation

FILE* rc_environ_fd

Plugins should write FOO=BAR to this fd to set any environment variables they wish. Variables should be separated by NULLs.


Generated on Tue Sep 25 16:24:20 2007 for rc by  doxygen 1.5.3