nih/child.h

/* libnih
 *
 * Copyright © 2009 Scott James Remnant <scott@netsplit.com>.
 * Copyright © 2009 Canonical Ltd.
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

#ifndef NIH_CHILD_H
#define NIH_CHILD_H

#include <sys/types.h>
#include <sys/wait.h>
#include <sys/ptrace.h>

#include <linux/ptrace.h>

#include <nih/macros.h>
#include <nih/list.h>


/**
 * NihChildEvents:
 *
 * Events that can occur for child processes, and used to determine the
 * content of the translated status field.  For NIH_CHILD_EXITED this will
 * contain the exit status of the program; for NIH_CHILD_PTRACE this will
 * contain one of the PTRACE_EVENT_* constants; otherwise this will
 * contain the signal that killed, dumped, stopped or continued the process
 * or was trapped through ptrace.
 **/
typedef enum {
	NIH_CHILD_NONE      = 0000,
	NIH_CHILD_EXITED    = 0001,
	NIH_CHILD_KILLED    = 0002,
	NIH_CHILD_DUMPED    = 0004,
	NIH_CHILD_STOPPED   = 0010,
	NIH_CHILD_CONTINUED = 0020,
	NIH_CHILD_TRAPPED   = 0040,
	NIH_CHILD_PTRACE    = 0100,
	NIH_CHILD_ALL       = 0177
} NihChildEvents;

/**
 * NihChildHandler:
 * @data: data pointer given with callback,
 * @pid: process that changed,
 * @event: event that occurred on the child,
 * @status: exit status of process, signal that killed it or ptrace event.
 *
 * A child handler is a function called for events on the child process
 * obtained through waitid().
 **/
typedef void (*NihChildHandler) (void *data, pid_t pid,
				 NihChildEvents event, int status);

/**
 * NihChildWatch:
 * @entry: list header,
 * @pid: process id to watch or -1,
 * @events: events to watch for,
 * @handler: function called when events occur to child,
 * @data: pointer passed to @reaper.
 *
 * This structure represents a watch on a particular child, the @reaper
 * function is called when an event in @events occurs to a child with
 * process id @pid.  If @pid is -1 then this function is called when @events
 * occur for all processes.
 *
 * The watch can be cancelled by calling nih_list_remove() on the structure
 * as they are held in a list internally.
 **/
typedef struct nih_child_watch {
	NihList          entry;
	pid_t            pid;
	NihChildEvents   events;

	NihChildHandler  handler;
	void            *data;
} NihChildWatch;


NIH_BEGIN_EXTERN

extern NihList *nih_child_watches;


void           nih_child_init      (void);

NihChildWatch *nih_child_add_watch (const void *parent, pid_t pid,
				    NihChildEvents events,
				    NihChildHandler handler, void *data)
	__attribute__ ((warn_unused_result, malloc));

void           nih_child_poll      (void);

NIH_END_EXTERN

#endif /* NIH_CHILD_H */