Core event system.

---

Detailed Description

The core event system includes the basic interfaces for event generation and handling. The first thing that must be done in this interface is to initialize an event context, using the event_init() function--this function loads the engine module(s) and initializes them. This context must be passed to virtually every other function in the library, and stores critical information about the engine selected, the event queue, library options, etc.

Files
file	event.h
	Core event system header file.
Data Structures
struct	_ev_englist_s
	Event context engine list structure. More...
struct	_ev_ctx_s
	Event context structure. More...
struct	_event_s
	Event structure. More...
struct	_ev_genhdr_s
	Event generator header structure. More...
Defines
#define	EV_CTX_MAGIC
	Event context magic number.
#define	EV_CTX_SECURE
	Secure operation flag.
#define	EV_CTX_RUNNING
	Library running flag.
#define	ec_verify(ctx)
	Event context verification macro.
#define	ec_flags(ctx)
	Event context flags.
#define	ec_prog(ctx)
	Event Context application name.
#define	ec_conf(ctx)
	Event Context configuration.
#define	EVENT_MAGIC
	Event magic number.
#define	ev_verify(event)
	Event verification macro.
#define	ev_context(event)
	Event context.
#define	ev_type(event)
	Event type.
#define	ev_generator(event)
	Event generator.
#define	ev_paramtype(event)
	Event parameter type.
#define	ev_intparam(event)
	Event parameter: integer.
#define	ev_ptrparam(event)
	Event parameter: pointer.
#define	EV_GEN_ACTIVE
	Generator in use.
#define	EV_GEN_DELETED
	Generator deleted.
#define	_eg_hdr(gen)
	Generator header.
#define	eg_verify(gen, magic)
	Generator verification macro.
#define	eg_type(gen)
	Generator type.
#define	eg_flags(gen)
	Generator flags.
#define	eg_flags_set(gen, fl)
	Set generator flags.
#define	eg_flags_clr(gen, fl)
	Clear generator flags.
#define	eg_next(gen)
	Next generator.
#define	eg_prev(gen)
	Previous generator.
#define	eg_context(gen)
	Generator context.
#define	eg_ref(gen)
	Retrieve reference count.
#define	eg_ref_inc(ctx, gen)
	Increment reference count.
#define	eg_ref_dec(ctx, gen)
	Decrement reference count.
#define	eg_callback(gen)
	Generator callback.
#define	eg_callback_set(gen, call)
	Set generator callback.
#define	eg_calldata(gen)
	Generator callback data.
#define	eg_calldata_set(gen, data)
	Set generator callback data.
#define	EV_INIT_SECURE
	Secure operation flag.
Typedefs
typedef _ev_ctx_s	ev_ctx_t
	Event context.
typedef _ev_englist_s	_ev_englist_t
	Event context engine list.
typedef _ev_attr_s *	ev_attr_t
	Event context attributes.
typedef _event_s	event_t
	Event structure.
typedef _ev_genhdr_s	ev_genhdr_t
	Generator header.
typedef unsigned int	ev_err_t
	Event errors.
typedef unsigned long	ev_magic_t
	Event magic number.
typedef unsigned long	ev_flags_t
	Event flags.
typedef void(*	ev_call_t )(ev_ctx_t *ctx, event_t *event, void *data)
	Event callbacks.
typedef void(*	ev_log_t )(const char *file, int line, const char *func, const char *msg)
	Library logging.
typedef void(*	ev_freegen_t )(ev_ctx_t *ctx, void *gen)
	Generator release callback.
Enumerations
enum	ev_type_t {   ET_NONE, ET_READ, ET_WRITE, ET_ACCEPT,   ET_CONNECT, ET_EOF, ET_ERROR, ET_SIGNAL,   ET_EXPIRE, ET_RESERVED, ET_USER }
	Event types. More...
enum	ev_paramtype_t { EP_NONE, EP_INT, EP_PTR }
	Event parameter types. More...
enum	ev_gentype_t {   EGT_NONE, EGT_SOCKET, EGT_SIGNAL, EGT_TIMER,   EGT_RESERVED, EGT_USER }
	Generator types. More...
Functions
ev_err_t	event_init (ev_ctx_t *ctx, const ev_attr_t *attr, ev_flags_t flags, const char *prog, const char *envpath)
	Initialize events library.
ev_err_t	event_destroy (ev_ctx_t *ctx)
	Release memory used by events library context.
ev_err_t	event_attr_init (ev_attr_t *attr)
	Initialize a set of attributes for the events library.
ev_err_t	event_attr_confpath (ev_attr_t *attr, const char **path)
	Retrieve and/or set default configuration search path.
ev_err_t	event_attr_libpath (ev_attr_t *attr, const char **path)
	Retrieve and/or set default module search path.
ev_err_t	event_attr_modlist (ev_attr_t *attr, const char **list)
	Retrieve and/or set default module list.
ev_err_t	event_attr_confreg (ev_attr_t *attr, const char *name, const char *def, treeconf_nodown_t nodown, treeconf_change_t change, void *assoc)
	Register a treeconf variable for the application.
ev_err_t	event_attr_confvar (ev_attr_t *attr, const char *name, const char *value)
	Override a treeconf variable setting.
ev_err_t	event_attr_destroy (ev_attr_t *attr)
	Destroy an attribute set and release all allocated memory.
ev_err_t	event_gen_register (ev_ctx_t *ctx, unsigned int gentype, ev_magic_t genmagic, size_t gensize, ev_freegen_t genrel)
	Register a generator.
ev_err_t	event_gen_alloc (ev_ctx_t *ctx, unsigned int gentype, void *gen)
	Allocate a generator.
ev_err_t	event_gen_release (ev_ctx_t *ctx, ev_genhdr_t *gen)
	Release a generator.
ev_err_t	event_log_set (ev_log_t logger)
	Set a logging function.
ev_err_t	event_log_reset (void)
	Reset library logging.
ev_err_t	event_log_debug (int onoff)
	Turn library logging on or off.
ev_err_t	event_log_trace (int onoff)
	Turn library function tracing on or off.
ev_err_t	event_log_abort (int onoff)
	Turn library abort on or off.

---

Define Documentation

#define _eg_hdr (  gen   )

For internal use only. This macro retrieves a pointer to an ev_genhdr_t given a generator. (All generators MUST begin with an ev_genhdr_t!) Parameters: [in]  gen  A pointer to a structure beginning with an ev_genhdr_t. Returns: A pointer to an ev_genhdr_t. Definition at line 632 of file event.h.

#define ec_conf (  ctx   )

This macro retrieves a pointer to a treeconf_ctx_t containing the current configuration of the library. See the treeconf_ctx_t documentation for more information. Parameters: [in]  ctx  A pointer to an ev_ctx_t. Returns: A pointer to a treeconf_ctx_t containing the library configuration. Definition at line 478 of file event.h. Referenced by event_destroy(), and event_init().

#define ec_flags (  ctx   )

This macro retrieves the flags set for the ev_ctx_t. Parameters: [in]  ctx  A pointer to an ev_ctx_t. Returns: The flags set for the ev_ctx_t. Definition at line 453 of file event.h. Referenced by event_destroy().

#define ec_prog (  ctx   )

This macro retrieves the application name set with the call to event_init(). Parameters: [in]  ctx  A pointer to an ev_ctx_t. Returns: A pointer to a constant string containing the application name. Definition at line 465 of file event.h.

#define ec_verify (  ctx   )

This macro verifies that a given pointer actually does point to an ev_ctx_t. Warning: This macro evaluates the ctx argument twice. Parameters: [in]  ctx  A pointer to an ev_ctx_t. Returns: Boolean true if ctx is a valid event context or false otherwise. Definition at line 443 of file event.h. Referenced by engine_activate(), engine_register(), event_destroy(), event_gen_alloc(), event_gen_register(), event_gen_release(), main(), signal_create(), signal_destroy(), timer_create(), timer_destroy(), and timer_resched().

#define eg_callback (  gen   )

This macro returns a pointer to the event callback function for the generator. Parameters: [in]  gen  A pointer to an ev_genhdr_t. Returns: An ev_call_t, a pointer to a callback function. Definition at line 773 of file event.h.

#define eg_callback_set (  gen, call   )

This macro may be used to set the generator callback function. Parameters: [in]  gen  A pointer to an ev_genhdr_t. [in]  call  An ev_call_t pointing to the callback function. Definition at line 783 of file event.h. Referenced by signal_create(), and timer_create().

#define eg_calldata (  gen   )

This macro returns a pointer to application-specific data to be passed to the event callback function. It may be used as an lvalue to set this data. Parameters: [in]  gen  A pointer to an ev_genhdr_t. Returns: A pointer to void containing the callback function data. Definition at line 797 of file event.h.

#define eg_calldata_set (  gen, data   )

This macro may be used to set the generator callback function data. Parameters: [in]  gen  A pointer to an ev_genhdr_t. [in]  data  A pointer to void containing the callback function data. Definition at line 808 of file event.h. Referenced by signal_create(), and timer_create().

#define eg_context (  gen   )

This macro returns a pointer to the context associated with the generator. Parameters: [in]  gen  A pointer to an ev_genhdr_t. Returns: A pointer to an ev_ctx_t. Definition at line 725 of file event.h. Referenced by signal_destroy(), timer_destroy(), and timer_resched().

#define eg_flags (  gen   )

This macro returns the flags set for the generator. Parameters: [in]  gen  A pointer to an ev_genhdr_t. Returns: The flags set for the ev_genhdr_t. Definition at line 672 of file event.h. Referenced by signal_destroy(), timer_destroy(), and timer_resched().

#define eg_flags_clr (  gen, fl   )

This macro clears a specific (or a set of specific) flags on the given generator. Parameters: [in]  gen  A pointer to an ev_genhdr_t. [in]  fl  A set of flags to clear. Definition at line 692 of file event.h. Referenced by timer_resched().

#define eg_flags_set (  gen, fl   )

This macro sets a specific (or a set of specific) flags on the given generator. Parameters: [in]  gen  A pointer to an ev_genhdr_t. [in]  fl  A set of flags to set. Definition at line 682 of file event.h. Referenced by signal_destroy(), timer_destroy(), and timer_resched().

#define eg_next (  gen   )

This macro returns a pointer to the next generator in the generator linked list. Parameters: [in]  gen  A pointer to an ev_genhdr_t. Returns: A pointer to the next ev_genhdr_t. Definition at line 703 of file event.h.

#define eg_prev (  gen   )

This macro returns a pointer to the previous generator in the generator linked list. Parameters: [in]  gen  A pointer to an ev_genhdr_t. Returns: A pointer to the previous ev_genhdr_t. Definition at line 714 of file event.h.

#define eg_ref (  gen   )

This macro returns the reference count for the generator. Parameters: [in]  gen  A pointer to an ev_genhdr_t. Returns: An unsigned int specifying the current reference count for the generator. Definition at line 736 of file event.h.

#define eg_ref_dec (  ctx, gen   )

This macro decrements the reference count for a generator. If the reference count hits zero and the EV_GEN_DELETED flag is set, the generator will be released by a call to event_gen_release(). Parameters: [in]  ctx  A pointer to an ev_ctx_t. [in]  gen  A pointer to an ev_genhdr_t. Definition at line 757 of file event.h. Referenced by signal_destroy(), timer_destroy(), and timer_resched().

#define eg_ref_inc (  ctx, gen   )

This macro simply increments the reference count for the generator. Parameters: [in]  ctx  A pointer to an ev_ctx_t. [in]  gen  A pointer to an ev_genhdr_t. Definition at line 746 of file event.h. Referenced by signal_create(), and timer_create().

#define eg_type (  gen   )

This macro returns the type of generator described by the argument gen. See ev_gentype_t for more information on the values this field may take. Warning: This macro evaluates the gen argument twice. Parameters: [in]  gen  A pointer to an ev_genhdr_t. Returns: An integer describing the type of generator. Definition at line 662 of file event.h.

#define eg_verify (  gen, magic   )

This macro verifies a generator to ensure that the pointer actually belongs to the specified type of generator. Warning: This macro evaluates the gen argument twice. Parameters: [in]  gen  A pointer to an ev_genhdr_t. [in]  magic  A magic number for the specific type of generator. Returns: Boolean true if gen is a valid generator with the given magic or false otherwise. Definition at line 648 of file event.h. Referenced by event_gen_release().

#define ev_context (  event   )

This macro retrieves the context from the given event. Parameters: [in]  event  A pointer to an event_t. Returns: A pointer to an ev_ctx_t. Definition at line 528 of file event.h.

#define EV_CTX_MAGIC

This is the magic number used for the event context structure. Definition at line 415 of file event.h. Referenced by event_init().

#define EV_CTX_RUNNING

This flag, if set, indicates that the library is running. Definition at line 429 of file event.h. Referenced by event_destroy().

#define EV_CTX_SECURE

This flag, if set, indicates that the library has been configured for secure operation. This may be done by passing the EV_INIT_SECURE flag to event_init(). Definition at line 423 of file event.h. Referenced by event_init().

#define EV_GEN_ACTIVE

This flag is used to indicate that a given generator is in use by the library. Definition at line 612 of file event.h. Referenced by event_gen_release().

#define EV_GEN_DELETED

This flag is used by generator handlers to indicate that a given generator is in the process of being deleted. Definition at line 619 of file event.h. Referenced by signal_destroy(), timer_destroy(), and timer_resched().

#define ev_generator (  event   )

This macro retrieves the responsible generator from the given event. Parameters: [in]  event  A pointer to an event_t. Returns: A pointer to an ev_genhdr_t describing the generator of the event. Definition at line 551 of file event.h.

#define EV_INIT_SECURE

This flag is used to advise the library that the program is being run setuid. Certain insecure elements of the file list will be skipped, and the EV_CTX_SECURE flag of the context structure will be set for the benefit of other library code. Definition at line 880 of file event.h. Referenced by event_init().

#define ev_intparam (  event   )

This macro retrieves an integer parameter from the given event. Parameters: [in]  event  A pointer to an event_t. Returns: An integer associated with the event. Definition at line 573 of file event.h.

#define ev_paramtype (  event   )

This macro retrieves the type of parameter associated with the given event, if any. It is one of the values in ev_paramtype_t. Parameters: [in]  event  A pointer to an event_t. Returns: A value consistent with ev_paramtype_t. Definition at line 563 of file event.h.

#define ev_ptrparam (  event   )

This macro retrieves a pointer parameter from the given event. Parameters: [in]  event  A pointer to an event_t. Returns: A pointer associated with the event. Definition at line 583 of file event.h.

#define ev_type (  event   )

This macro retrieves the event type from the given event. Parameters: [in]  event  A pointer to an event_t. Returns: An integer specifying a value in ev_type_t or a library-defined or user-defined event type. Definition at line 539 of file event.h.

#define ev_verify (  event   )

This macro verifies that a given pointer actually does point to an event_t. Warning: This macro evaluates the event argument twice. Parameters: [in]  event  A pointer to an event_t. Returns: Boolean true if event is a valid event or false otherwise. Definition at line 518 of file event.h.

#define EVENT_MAGIC

This is the magic number used for the event structure. Definition at line 504 of file event.h.

---

Typedef Documentation

typedef struct _ev_englist_s _ev_englist_t

For internal use only. This type is a helper type for the event context structure. It is used to represent a list of active event engines. Definition at line 216 of file event.h.

typedef struct _ev_attr_s* ev_attr_t

Event context attributes is a catch-all for configuration of the event library at initialization time. If a NULL pointer is passed to the event_init() function, default values will be used for all the configurable variables. Definition at line 225 of file event.h.

typedef void(* ev_call_t)(ev_ctx_t *ctx, event_t *event, void *data)

Generators may optionally have a callback associated with them. (Callbacks are required if the library is operated in event loop mode.) All callbacks are pointers to functions taking a pointer to the event context and a pointer to the event for which the callback is being called, along with a generic pointer for user-defined data. Parameters: [in]  ctx  A pointer to an ev_ctx_t. [in]  event  A pointer to an event_t specifying the event. [in]  data  A pointer to void containing auxiliary data for the callback function. Definition at line 341 of file event.h.

typedef struct _ev_ctx_s ev_ctx_t

The event context structure is the core of the event system. Virtually every function in the library requires a pointer to an initialized context. It is initialized with the event_init() function and destroyed with event_destroy(). Definition at line 208 of file event.h.

typedef unsigned int ev_err_t

Almost all functions in the library have an error code as a return value. This error code may be passed to com_err() and related functions, if the library has been compiled with com_err() support, to generate error messages. A 0 return value always means "Success." Definition at line 309 of file event.h.

typedef unsigned long ev_flags_t

Several functions and some structures use flags to modify behavior or store boolean (on or off) information. This type is large enough to store up to 32 different flags. Definition at line 323 of file event.h.

typedef void(* ev_freegen_t)(ev_ctx_t *ctx, void *gen)

The library keeps a list of active generators. When event_destroy() is called, a generator-specific release function may be called. This type is a pointer to a generator-specific release function for active generators. Parameters: [in]  ctx  A pointer to an ev_ctx_t. [in]  gen  A pointer to void specifying the generator to be released. Definition at line 375 of file event.h.

typedef struct _ev_genhdr_s ev_genhdr_t

All events are associated with a generator. Generators are abstract objects, such as sockets, that generate events, such as readability. All generators must begin with an instance of the ev_genhdr_t structure containing a unique magic number. Definition at line 242 of file event.h.

typedef void(* ev_log_t)(const char *file, int line, const char *func, const char *msg)

The library includes support for self-debugging. By default, logs will be written to stderr. However, the application may provide its own logging function, which must have a signature compatible with this type. The logging function will be called with the file name, line number, function name (if available; if not, NULL will be passed), and a log message. For more information, see event_log_set(), event_log_reset(), event_log_debug(), and event_log_trace(). Parameters: [in]  file  The file name. [in]  line  The line number in the file. [in]  func  The name of the containing function, or NULL if function names are not available. [in]  msg  The log message. Definition at line 361 of file event.h.

typedef unsigned long ev_magic_t

This type is used for structure magic numbers. Definition at line 315 of file event.h.

typedef struct _event_s event_t

This is the workhorse of the library. All events are represented by an instance of this structure. It is returned by event_poll() and is passed to callback functions. Definition at line 233 of file event.h.

---

Enumeration Type Documentation

enum ev_gentype_t

All generators have an generator type describing the kind of generator. Generator typess in the range from EGT_RESERVED to EGT_USER (10-100) are reserved for application libraries, such as resolvers. Generator types above EGT_USER (100) are specifically reserved for applications. All generators must be registered using event_gen_register() in order to allocate space for the generator linked list. Enumerator: EGT_NONE  No such generator. EGT_SOCKET  Generator is a socket. EGT_SIGNAL  Generator is a signal. EGT_TIMER  Generator is a timer. EGT_RESERVED  Generator types in this range are reserved. EGT_USER  Beginning of the user-defined generator types. Definition at line 289 of file event.h.

enum ev_paramtype_t

Events may optionally have a parameter. This enumeration specifies the generic type of this parameter. Enumerator: EP_NONE  No parameter associated with event. EP_INT  Integer parameter associated with event. EP_PTR  Pointer parameter associated with event. Definition at line 273 of file event.h.

enum ev_type_t

All events have an event type describing the kind of event that was generated. Event types in the range from ET_RESERVED to ET_USER (100-1000) are reserved for application libraries, such as resolvers. Event types above ET_USER (1000) are specifically reserved for applications. Enumerator: ET_NONE  No event has occurred. ET_READ  Data is available on a socket for reading. ET_WRITE  Data can be written to a socket. ET_ACCEPT  A connection can be accepted on the socket. ET_CONNECT  A connection attempt has completed. ET_EOF  End-of-file on the socket. ET_ERROR  An error has occurred on the socket. ET_SIGNAL  A signal has been received. ET_EXPIRE  A timer has expired. ET_RESERVED  Event types in this range are reserved. ET_USER  Beginning of the user-defined event types. Definition at line 252 of file event.h.

---

Function Documentation

ev_err_t event_attr_confpath (  ev_attr_t *  attr, const char **  path )

The event_init() function loads several configuration files, based on a specified search path and a compiled-in default. This compiled-in default may be examined or overridden using this function. Test: This function is tested in t_event_attrs.c. Parameters: [in]  attr  A pointer to an ev_attr_t. [in,out]  path  This is a value-result parameter. On return, path will be modified to point to the original value of the confpath attribute. If the pointer path pointed to was NULL, no other action is taken; otherwise, the confpath attribute will now be this value. Note that this string value is not copied; the pointer MUST NOT go out of scope. Return values: EINVAL  An invalid argument was given. Definition at line 32 of file event_attr_confpath.c. References ea_confpath, ea_verify, ev_init, and ev_return. Referenced by main().

ev_err_t event_attr_confreg (  ev_attr_t *  attr, const char *  name, const char *  def, treeconf_nodown_t  nodown, treeconf_change_t  change, void *  assoc )

The event_init() function registers a couple of library-specific treeconf configuration variables. This function enables the application to specify a list of variables to be registered for its use. Note that any errors will only be discovered by event_init(). Test: This function is tested in t_event_attrs.c. Parameters: [in]  attr  A pointer to an ev_attr_t. [in]  name  A pointer to char indicating the fully-qualified name of the configuration variable. [in]  def  A pointer to char indicating the default value of the configuration variable. If NULL, a tree node will be created. [in]  nodown  A treeconf_nodown_t function pointer. See the documentation for tc_register() for more information about this parameter. [in]  change  A treeconf_change_t function pointer. See the documentation for tc_register() for more information about this parameter. [in]  assoc  A pointer to void containing application-specific association data. Return values: EINVAL  An invalid argument was given. ENOMEM  Out of memory. Definition at line 35 of file event_attr_confreg.c. References ea_varlist, ea_verify, ev_init, ev_return, _ev_varlist_s::vl_assoc, _ev_varlist_s::vl_change, _ev_varlist_s::vl_default, _ev_varlist_s::vl_name, _ev_varlist_s::vl_next, _ev_varlist_s::vl_nodown, and _ev_varlist_s::vl_prev_p. Referenced by main().

ev_err_t event_attr_confvar (  ev_attr_t *  attr, const char *  name, const char *  value )

Applications may desire to use some other form of configuration, rather than treeconf configuration files. This function allows the application to explicitly override the value of any variable in the configuration file(s) loaded by event_init(). Note that any errors will only be discovered by event_init(). Test: This function is tested in t_event_attrs.c. Parameters: [in]  attr  A pointer to an ev_attr_t. [in]  name  A pointer to char indicating the fully-qualified name of the configuration variable. [in]  value  A pointer to char indicating the desired value of the configuration variable. If NULL, the variable will be reset to its default value. Return values: EINVAL  An invalid argument was given. ENOMEM  Out of memory. Definition at line 35 of file event_attr_confvar.c. References ea_ovars, ea_verify, ev_init, ev_return, _ev_overvars_s::ov_name, _ev_overvars_s::ov_next, _ev_overvars_s::ov_prev_p, and _ev_overvars_s::ov_value. Referenced by main().

ev_err_t event_attr_destroy (  ev_attr_t *  attr  )

The memory allocated by event_attr_init() must be released to the system with a call to this function. Test: This function is tested in t_event_attrs.c. Parameters: [in]  attr  A pointer to an ev_attr_t. Return values: EINVAL  An invalid argument was given. Definition at line 35 of file event_attr_destroy.c. References ea_ovars, ea_varlist, ea_verify, ev_init, ev_return, _ev_overvars_s::ov_next, and _ev_varlist_s::vl_next. Referenced by main().

ev_err_t event_attr_init (  ev_attr_t *  attr  )

The event_init() function takes an optional set of attributes that may be used to configure various aspects of the library. This routine is used to create an attribute set which may be manipulated and then passed to event_init(). Note that this function allocates memory that must be returned to the system by calling event_attr_destroy() once event_init() returns. Test: This function is tested in t_event_attrs.c. Parameters: [in,out]  attr  A pointer to an ev_attr_t. Return values: EINVAL  An invalid argument was given. ENOMEM  Out of memory. Definition at line 34 of file event_attr_init.c. References _ev_defattr, ev_init, and ev_return. Referenced by main().

ev_err_t event_attr_libpath (  ev_attr_t *  attr, const char **  path )

The event_init() function loads several modules, based on a module search path and a list of modules to load. The compiled-in default for the module search path may be examined or overridden using this function. Test: This function is tested in t_event_attrs.c. Parameters: [in]  attr  A pointer to an ev_attr_t. [in,out]  path  This is a value-result parameter. On return, path will be modified to point to the original value of the libpath attribute. If the pointer path pointed to was NULL, no other action is taken; otherwise, the libpath attribute will now be this value. Note that this string value is not copied; the pointer MUST NOT go out of scope. Return values: EINVAL  An invalid argument was given. Definition at line 32 of file event_attr_libpath.c. References ea_libpath, ea_verify, ev_init, and ev_return. Referenced by main().

ev_err_t event_attr_modlist (  ev_attr_t *  attr, const char **  list )

The event_init() function loads several modules, based on a module search path and a list of modules to load. The compiled-in default for the module list may be examined or overridden using this function. Test: This function is tested in t_event_attrs.c. Parameters: [in]  attr  A pointer to an ev_attr_t. [in,out]  list  This is a value-result parameter. On return, list will be modified to point to the original value of the modlist attribute. If the pointer list pointed to was NULL, no other action is taken; otherwise, the modlist attribute will now be this value. Note that this string value is not copied; the pointer MUST NOT go out of scope. Return values: EINVAL  An invalid argument was given. Definition at line 32 of file event_attr_modlist.c. References ea_modlist, ea_verify, ev_init, and ev_return. Referenced by main().

ev_err_t event_destroy (  ev_ctx_t *  ctx  )

This function simply destroys the event context that was created and initialized by event_init(), releasing all memory back to the system. Test: This function is tested in t_event_init.c. Parameters: [in]  ctx  A pointer to an ev_ctx_t to be destroyed. Return values: EINVAL  An invalid argument was given. EBUSY  Context is actively running. Definition at line 34 of file event_destroy.c. References _ev_debug(), _gca_func, ec_conf, _ev_ctx_s::ec_engine, _ev_ctx_s::ec_evcnt, _ev_ctx_s::ec_evs, ec_flags, _ev_ctx_s::ec_flags, _ev_ctx_s::ec_gens, _ev_ctx_s::ec_magic, _ev_ctx_s::ec_maxgen, _ev_ctx_s::ec_signal, _ev_ctx_s::ec_socket, _ev_ctx_s::ec_timer, ec_verify, _ev_genhdr_s::eg_next, _ev_genhdr_s::eg_prev, _ev_englist_s::el_first, _ev_englist_s::el_last, _ev_englink_s::el_next, _ev_engine_s::eng_fini, eng_fini, _ev_engine_s::eng_handle, _ev_engine_s::eng_list, _ev_engine_s::eng_runfl, ev_assert, EV_CTX_LTDLINIT, EV_CTX_RUNNING, EV_ENGINE_RUNNING, ev_init, _event_s::ev_next, ev_return, EVAS_LOG, _ev_gendesc_s::gd_active, _ev_gendesc_s::gd_free, _ev_gendesc_s::gd_release, _ev_genlist_s::gl_count, _ev_genlist_s::gl_list, _ev_gens_s::gs_count, _ev_gens_s::gs_first, _ev_gens_s::gs_gens, _ev_gens_s::gs_next, and tc_destroy(). Referenced by event_init(), and main(). Here is the call graph for this function:

ev_err_t event_gen_alloc (  ev_ctx_t *  ctx, unsigned int  gentype, void *  gen )

This function will allocate a generator of the given type, initializing all the common header components as necessary. In cooperation with event_gen_release(), it maintains a free list to help reduce memory fragmentation. Test: This function is tested in t_evg_alloc.c. Parameters: [in]  ctx  A pointer to an ev_ctx_t. [in]  gentype  A generator type previously passed to event_gen_register(). [in,out]  gen  A pointer to a pointer to an event generator structure, which will be used to return the allocated generator to the caller. Note that the argument type is pointer to void to stomp a warning having to do with strict aliasing in C99. Return values: EINVAL  An invalid argument was given. ENOENT  No such generator has been registered. ENOMEM  Out of memory. Definition at line 34 of file event_gen_alloc.c. References _ev_gen_lookup(), ec_verify, _ev_genhdr_s::eg_next, _ev_genhdr_s::eg_prev, ev_assert, ev_gen_init, ev_init, ev_return, _ev_gendesc_s::gd_active, _ev_gendesc_s::gd_free, _ev_gendesc_s::gd_size, _ev_genlist_s::gl_count, and _ev_genlist_s::gl_list. Referenced by main(), signal_create(), and timer_create(). Here is the call graph for this function:

ev_err_t event_gen_register (  ev_ctx_t *  ctx, unsigned int  gentype, ev_magic_t  genmagic, size_t  gensize, ev_freegen_t  genrel )

Generators must be registered with the library before they may be used. This function is used to register a generator. Part of the reason for this is free list management. Test: This function is tested in t_evg_register.c. Parameters: [in]  ctx  A pointer to an ev_ctx_t. [in]  gentype  A generator type; one of the values from ev_gentype_t, or a user-allocated offset from EGT_USER. [in]  genmagic  The magic number used by the generator. [in]  gensize  The size of the generator structure. [in]  genrel  A function to release a generator from event_destroy(). Return values: EINVAL  An invalid argument was given. ENOMEM  Out of memory. EV_ERR_DUPGEN  The generator has already been registered. Definition at line 270 of file event_gen_register.c. References _ev_ctx_s::ec_gens, ec_verify, EGT_NONE, ev_assert, ev_init, ev_return, generator::genmagic, generator::genrel, gens_construct(), gens_extend(), gens_merge(), generator::gensize, generator::gentype, _ev_gens_s::gs_count, _ev_gens_s::gs_first, and _ev_gens_s::gs_next. Referenced by event_init(), and main(). Here is the call graph for this function:

ev_err_t event_gen_release (  ev_ctx_t *  ctx, ev_genhdr_t *  gen )

This function will release a generator allocated by event_gen_alloc(). It maintains a free list in cooperation with event_gen_alloc() in order to reduce memory fragmentation. Test: This function is tested in t_evg_alloc.c. Parameters: [in]  ctx  A pointer to an ev_ctx_t. [in]  gen  A pointer to an ev_genhdr_t to be released to the system. Return values: EINVAL  An invalid argument was given. ENOENT  No such generator has been registered. EBUSY  The generator is in use. Definition at line 34 of file event_gen_release.c. References _ev_gen_lookup(), ec_verify, _ev_genhdr_s::eg_flags, _ev_genhdr_s::eg_next, _ev_genhdr_s::eg_prev, _ev_genhdr_s::eg_type, eg_verify, EV_GEN_ACTIVE, ev_init, ev_return, _ev_gendesc_s::gd_active, _ev_gendesc_s::gd_free, _ev_gendesc_s::gd_magic, _ev_genlist_s::gl_count, and _ev_genlist_s::gl_list. Referenced by main(), signal_create(), and timer_create(). Here is the call graph for this function:

ev_err_t event_init (  ev_ctx_t *  ctx, const ev_attr_t *  attr, ev_flags_t  flags, const char *  prog, const char *  envpath )

This function is used to initialize the library context. It will load configuration data from all the files listed in the envpath parameter (or from a default list if envpath is NULL) and load and initialize the event engines. Certain flags may be given to modify the behavior of event_init(); for instance, EV_INIT_SECURE inhibits use of insecure files in envpath. Finally, certain library options may be specified through use of the attr parameter. See the documentation for ev_attr_t for more information on how to manipulate the library parameters. Test: This function is tested in t_event_init.c. Parameters: [in,out]  ctx  A pointer to an ev_ctx_t. [in]  attr  A pointer to an ev_attr_t containing library options. If NULL is passed, the library defaults will be used. [in]  flags  A bit-wise OR of 0 or more flags. [in]  prog  A pointer to the name of the current program. This pointer must not go out of scope. It is advised to use a string literal or memory allocated with malloc(). [in]  envpath  A pointer to a colon-separated list of configuration files to be located and loaded. If NULL, a compiled-in default will be used. Note that an empty element in the list will also cause the default list to be searched. Return values: EINVAL  An invalid argument was given. ENOMEM  Out of memory. EV_ERR_LIBLTDL  The libltdl library failed to initialize. EV_ERR_NOENGINE  One or more engine components was not initialized. Definition at line 333 of file event_init.c. References ea_confpath, ea_engines, ea_libpath, ea_modlist, ea_ovars, ea_varlist, ea_verify, ec_conf, _ev_ctx_s::ec_engine, _ev_ctx_s::ec_evcnt, _ev_ctx_s::ec_evs, _ev_ctx_s::ec_flags, _ev_ctx_s::ec_gens, _ev_ctx_s::ec_magic, _ev_ctx_s::ec_maxgen, _ev_ctx_s::ec_prog, _ev_ctx_s::ec_signal, _ev_ctx_s::ec_socket, _ev_ctx_s::ec_timer, _ev_ctx_s::ec_timtree, EGT_SIGNAL, EGT_SOCKET, EGT_TIMER, _ev_englist_s::el_first, _ev_englist_s::el_last, _ev_englink_s::el_next, _ev_engine_s::eng_list, engine_load(), engine_register(), englink_clr, EV_CTX_LTDLINIT, EV_CTX_MAGIC, EV_CTX_SECURE, EV_ENGINE_COMPMASK, ev_init, EV_INIT_SECURE, ev_return, EV_SIG_MAGIC, EV_SOCK_MAGIC, EV_TIM_MAGIC, event_destroy(), event_gen_register(), new_modvar(), _ev_overvars_s::ov_name, _ev_overvars_s::ov_next, _ev_overvars_s::ov_value, substs, tc_break(), tc_get(), tc_init, tc_load(), tc_path(), TC_PATH_ALL, TC_PATH_SECURE, tc_register(), tc_set(), TC_SUBST_IGNORE, TC_SUBST_INIT, TC_SUBST_INSECURE, tu_flags, tu_value, VAR_LIBPATH, VAR_MODLIST, VAR_MODULES, _ev_varlist_s::vl_assoc, _ev_varlist_s::vl_change, _ev_varlist_s::vl_default, _ev_varlist_s::vl_name, _ev_varlist_s::vl_next, and _ev_varlist_s::vl_nodown. Referenced by main(). Here is the call graph for this function:

ev_err_t event_log_abort (  int  onoff  )

The library contains its own implementation of the C assert() macro. In particular, this macro results in a return (with the EV_ERR_ASSERT error code), rather than a call to abort(), as that is rather impolite for libraries to do. However, the library user may wish to allow the library to abort. This function allows the caller to turn library abort on or off, depending on the value of the onoff parameter. Test: This function is tested in t_event_log.c. Parameters: [in]  onoff  A TRUE value if aborting is desired; otherwise, a FALSE value to turn aborting off. Definition at line 120 of file event_log.c. References _ev_asflags, ev_init, ev_return, and EVAS_ABORT. Referenced by main().

ev_err_t event_log_debug (  int  onoff  )

By default, library logging is turned off. This function allows the caller to turn library logging on or off, depending on the value of the onoff parameter. Test: This function is tested in t_event_log.c. Parameters: [in]  onoff  A TRUE value if debug logging is desired; otherwise, a FALSE value to turn off debug logging. Definition at line 92 of file event_log.c. References _ev_asflags, ev_init, ev_return, and EVAS_LOG. Referenced by main().

ev_err_t event_log_reset (  void   )

This function resets the library logging to its default values--using a logging function that writes to stderr, and logging and tracing turned off, as if event_log_debug() and event_log_trace() had been called with a FALSE value for onoff. Test: This function is tested in t_event_log.c. Definition at line 80 of file event_log.c. References _ev_asflags, _ev_debuglog, deflog(), ev_init, ev_return, EVAS_LOG, and EVAS_TRACE. Referenced by main(). Here is the call graph for this function:

ev_err_t event_log_set (  ev_log_t  logger  )

This function is used to set the library logging callback. It will also implicitly turn on debug logging, as if event_log_debug() was called with a TRUE value for onoff. Test: This function is tested in t_event_log.c. Parameters: [in]  logger  An ev_log_t pointing to a user-defined logging function. Definition at line 68 of file event_log.c. References _ev_asflags, _ev_debuglog, ev_init, ev_return, and EVAS_LOG. Referenced by main().

ev_err_t event_log_trace (  int  onoff  )

The library is capable of logging each function entry. By default, this functionality is turned off. This function allows the caller to turn library function tracing on or off, depending on the value of the onoff parameter. Test: This function is tested in t_event_log.c. Parameters: [in]  onoff  A TRUE value if function tracing is desired; otherwise, a FALSE value to turn function tracing off. Definition at line 106 of file event_log.c. References _ev_asflags, ev_init, ev_return, and EVAS_TRACE. Referenced by main().

---