The DPCL system manages a variety of signals and file descriptors in order to enable analysis tools to effectively instrument one or more target application processes. As a programming convenience for you, the developer of DPCL analysis tools, the DPCL system enables you to add additional signals and file descriptors to the list of those it monitors. When these additional signals occur, or when these additional file descriptors are ready to be read, the DPCL system will call a function handler that you have specified. The DPCL function handlers are described in this chapter.
Synopsis
#include <AisHandler.h> typedef int (*AisHandlerType)(int fd_or_sig);
Description
Points to an event handler function that is called when a noteworthy event takes place. Noteworthy events occur when a file descriptor managed by the instrumentation system receives input, is ready to send output, or a signal managed by the instrumentation system has been raised.
The function returns an integer value with the following meaning. If the mechanism that generated the event is a file descriptor and the file descriptor reaches an end-of-file condition, the handler function is to return a value of -1. This indicates to the system that the file descriptor is to be closed and removed from the list of watched file descriptors. If the returned value is any other value than -1 or the event that occurred was a signal, the return value is ignored.
The following is an example of using AisHandlerType.
#include <AisHandler.h>
int main(int argc, char *argv[])
{
AisHandlerType handler;
int handler_type;
int socket;
handler_type = Ais_next_fd(socket, handler);
if (handler_type == 1) { // socket handler
handler(socket);
}
}
Synopsis
#include <AisHandler.h>
AisStatus Ais_add_fd(
int fd,
AisHandlerType handler);
Parameters
Description
Adds a file descriptor and input handler to the list of file descriptors managed by the instrumentation system. When input is received by the file descriptor, the handler is called to handle the input. The handler accepts the file descriptor as its input parameter.
Return Values
See Also
Ais_add_signal, Ais_next_fd, Ais_remove_fd,Ais_remove_signal
Synopsis
#include <AisHandler.h>
AisStatus Ais_add_signal(
int signal,
AisHandlerType handler);
Parameters
Description
Adds a signal and signal handler to the list of signals managed by the instrumentation system. When a signal is received, the handler is called to handle the signal. The handler accepts the signal as its input parameter. The instrumentation system ensures that signals registered with the instrumentation system will not interfere with its system calls.
Signal handlers executed by the instrumentation system are executed on the normal application stack. In the event that multiple signals occur while a signal handler is being executed, the executing handler is completed before the next handler is begun. This provides a measure of safety for operations that are normally considered unsafe for signal handlers, such as memory allocation.
Refer to signal.h for the possible signal types.
Return Values
See Also
Ais_add_fd, Ais_next_fd, Ais_remove_fd, Ais_remove_signal
Synopsis
#include <AisHandler.h> int Ais_next_fd( int &fd_or_sig, AisHandlerType &handler);
Parameters
Description
The fd_or_sig parameter returns the file descriptor or signal number and associated handler of the next event to occur. A return value of 0 indicates this is a signal handler. A return value of 1 indicates this is a file descriptor or socket.
See Also
Ais_add_fd, Ais_add_signal, Ais_remove_fd, Ais_remove_signal
Synopsis
#include <AisHandler.h> AisHandlerType Ais_query_signal(int signal);
Parameters
Description
Returns a pointer to the signal handler function for the specified signal, or NULL if there is none.
Return Values
Returns a pointer to the signal handler function for the specified signal, if there is one. Returns NULL if there is no handler or the signal parameter does not represent a valid signal.
See Also
Ais_add_fd, Ais_add_signal, Ais_next_fd, Ais_remove_fd
Synopsis
#include <AisHandler.h> AisStatus Ais_remove_fd(int fd);
Parameters
Description
Removes a file descriptor or socket from the list of descriptors the instrumentation system manages. The file descriptor is not affected by this operation (it is neither closed nor flushed).
Return Values
See Also
Ais_add_fd, Ais_add_signal, Ais_remove_fd, Ais_remove_signal
Synopsis
#include <AisHandler.h> AisStatus Ais_remove_signal(int signal);
Parameters
Description
Removes a signal and signal handler from the list of signals the instrumentation system manages. A previous handler is not restored for this signal.
Return Values
See Also
Ais_add_fd, Ais_add_signal, Ais_next_fd, Ais_remove_fd