The "dm" Package

These routines are meant to provide a generic and simple to use descriptor management facility (ie. event processing on pipes, connections and terminals). NOTE: THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

Library: karma
Link With: -lkarma

Functions

dm_manage	Manage a file descriptor for events.
dm_unmanage	Terminate the management of a file descriptor for activity.
dm_poll	Poll all managed descriptors for any activity.

Prototype Functions

DM_PROTO_input_func	Input event callback.
DM_PROTO_close_func	Close event callback.
DM_PROTO_output_func	Output event callback.
DM_PROTO_exception_func	Exception event callback.

Functions

flag dm_manage ( int fd, void *info, flag (*input_func) (), void (*close_func) (), flag (*output_func) (), flag (*exception_func) () )

This routine will manage a file descriptor for activity by registering callback routines. Only one set of callbacks may be registered per file descriptor.

Parameters:

fd : The file descriptor to manage.
info : The initial value of the arbitrary pointer associated with the managed descriptor. This pointer may be modified by the callback routines.
input_func : The routine which is called when new input occurrs on the descriptor. If this is NULL, no callback routine is installed. The prototype function is DM_PROTO_input_func.
close_func : The routine which is called when the descriptor closes. If this is NULL, no callback routine is installed. The prototype function is DM_PROTO_close_func.
output_func : The routine which is called when the descriptor becomes ready for output. If this is NULL, no callback routine is installed. The prototype function is DM_PROTO_output_func.
exception_func : The routine which is called when exceptions occurr on the descriptor. If this is NULL, no callback routine is installed. The prototype function is DM_PROTO_exception_func.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

void dm_unmanage (int fd)

Terminate the management of a file descriptor for activity.

Parameters:

fd : The descriptor to unmanage.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

The routine will NOT close the descriptor (nor does it assume the descriptor is open).

void dm_poll (long timeout_ms)

Poll all managed descriptors for any activity.

Parameters:

timeout_ms : The time (in milliseconds) to poll. If this is less than 0 the routine will poll forever (until some activity occurs or a signal is caught).

Returns: Nothing.
Multithreading Level: Unsafe

Prototype Functions

flag DM_PROTO_input_func (int fd, void **info)

This routine is called when new input occurs on a descriptor.

Parameters:

fd : The file descriptor.
info : A pointer to the arbitrary information pointer. The pointer written here will persist until the descriptor is unmanaged (or a subsequent callback routine changes it).

Returns: TRUE if the descriptor is to remain managed and open, else it returns FALSE (indicating that the descriptor is to be unmanaged and closed). This routine MUST NOT unmanage or close the descriptor.
Multithreading Level: Unsafe
Note:

The close_func will be called if this routine returns FALSE

void DM_PROTO_close_func (int fd, void *info)

This routine is called when a descriptor closes.

Parameters:

fd : The file descriptor. The descriptor MUST be capable of detecting closure if this routine is supplied (ie. this routine cannot be supplied for docks).
info : The arbitrary pointer for the managed descriptor.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

This routine MUST NOT unmanage the descriptor. The descriptor will be automatically unmanaged and deleted upon closure (even if no close_func is specified).
Any unread data in the descriptor will be lost upon closure. The call to this function is the last chance to read this data.

flag DM_PROTO_output_func (int fd, void **info)

This routine is called when a descriptor becomes ready for writing.

Parameters:

fd : The file descriptor.
info : A pointer to the arbitrary information pointer. The pointer written here will persist until the descriptor is unmanaged (or a subsequent callback routine changes it).

The close_func will be called if this routine returns FALSE

flag DM_PROTO_exception_func (int fd, void **info)

This routine is called when an exception occurrs on a descriptor.

Parameters:

fd : The file descriptor.
info : A pointer to the arbitrary information pointer. The pointer written here will persist until the descriptor is unmanaged (or a subsequent callback routine changes it).

The close_func will be called if this routine returns FALSE

Contact: Richard Gooch
Web Development: Ariel Internet Services