man/sd_event_add_child.3

   1 '\" t
   2 .TH "SD_EVENT_ADD_CHILD" "3" "" "systemd 217" "sd_event_add_child"
   3 .\" -----------------------------------------------------------------
   4 .\" * Define some portability stuff
   5 .\" -----------------------------------------------------------------
   6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7 .\" http://bugs.debian.org/507673
   8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
   9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10 .ie \n(.g .ds Aq \(aq
  11 .el       .ds Aq '
  12 .\" -----------------------------------------------------------------
  13 .\" * set default formatting
  14 .\" -----------------------------------------------------------------
  15 .\" disable hyphenation
  16 .nh
  17 .\" disable justification (adjust text to left margin only)
  18 .ad l
  19 .\" -----------------------------------------------------------------
  20 .\" * MAIN CONTENT STARTS HERE *
  21 .\" -----------------------------------------------------------------
  22 .SH "NAME"
  23 sd_event_add_child, sd_event_source_get_child_pid \- Add a child state change event source to an event loop
  24 .SH "SYNOPSIS"
  25 .sp
  26 .ft B
  27 .nf
  28 #include <systemd/sd\-bus\&.h>
  29 .fi
  30 .ft
  31 .HP \w'int\ sd_event_add_child('u
  32 .BI "int sd_event_add_child(sd_event\ *" "event" ", sd_event_source\ **" "source" ", pid_t\ " "pid" ", int\ " "options" ", sd_event_child_handler_t\ " "handler" ", void\ *" "userdata" ");"
  33 .HP \w'typedef\ int\ (*sd_event_child_handler_t)('u
  34 .BI "typedef int (*sd_event_child_handler_t)(sd_event_source\ *" "s" ", const\ siginfo_t\ *" "si" ", void\ *" "userdata" ");"
  35 .HP \w'int\ sd_event_source_get_child_pid('u
  36 .BI "int sd_event_source_get_child_pid(sd_event_source\ *" "source" ", pid_t\ *" "pid" ");"
  37 .SH "DESCRIPTION"
  38 .PP
  39 \fBsd_event_add_child()\fR
  40 adds a new child state change event source to an event loop object\&. The event loop is specified in
  41 \fIevent\fR, the event source is returned in the
  42 \fIsource\fR
  43 parameter\&. The
  44 \fIpid\fR
  45 parameter specifies the process to watch\&. The
  46 \fIhandler\fR
  47 must reference a function to call when the process changes state\&. The handler function will be passed the
  48 \fIuserdata\fR
  49 pointer, which may be chosen freely by the caller\&. The handler also receives a pointer to a
  50 const siginfo_t
  51 structure containing the information about the event\&. The
  52 \fIoptions\fR
  53 parameter determines which state changes will be watched for\&. It must contain an OR\-ed mask of
  54 \fBWEXITED\fR
  55 (watch for the child terminating),
  56 \fBWSTOPPED\fR
  57 (watch for the child being stopped by a signal), and
  58 \fBWCONTINUED\fR
  59 (watch for the child being resumed by a signal)\&. See
  60 \fBwaitid\fR(2)
  61 for futher information\&.
  62 .PP
  63 Only a single handler may be installed for a specific child\&. The handler is enabled for a single event (\fBSD_EVENT_ONESHOT\fR), but this may be changed with
  64 \fBsd_event_source_set_enabled\fR(3)\&. If the handler function returns a negative error code, it will be disabled after the invocation, even if
  65 \fBSD_EVENT_ON\fR
  66 mode is set\&.
  67 .PP
  68 \fBsd_event_source_get_child_pid()\fR
  69 retrieves the configured
  70 \fIpid\fR
  71 of a child state change event source created previously with
  72 \fBsd_event_add_child()\fR\&. It takes the event source object as the
  73 \fIsource\fR
  74 parameter and a pointer to
  75 \fBpid_t\fR
  76 to return the result in\&.
  77 .SH "RETURN VALUE"
  78 .PP
  79 On success, these functions return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
  80 .SH "ERRORS"
  81 .PP
  82 Returned errors may indicate the following problems:
  83 .PP
  84 \fB\-ENOMEM\fR
  85 .RS 4
  86 Not enough memory to allocate an object\&.
  87 .RE
  88 .PP
  89 \fB\-EINVAL\fR
  90 .RS 4
  91 An invalid argument has been passed\&. This includes specyfing an empty mask in
  92 \fIoptions\fR
  93 or a mask which constains values different than a combination of
  94 \fBWEXITED\fR,
  95 \fBWSTOPPED\fR, and
  96 \fBWCONTINUED\fR\&.
  97 .RE
  98 .PP
  99 \fB\-EBUSY\fR
 100 .RS 4
 101 An handler is already installed for this child\&.
 102 .RE
 103 .PP
 104 \fB\-ESTALE\fR
 105 .RS 4
 106 The event loop is already terminated\&.
 107 .RE
 108 .PP
 109 \fB\-ECHILD\fR
 110 .RS 4
 111 The event loop has been created in a different process\&.
 112 .RE
 113 .SH "NOTES"
 114 .PP
 115 \fBsd_event_add_child()\fR
 116 and the other functions described here are available as a shared library, which can be compiled and linked to with the
 117 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
 118 file\&.
 119 .SH "SEE ALSO"
 120 .PP
 121 \fBsystemd\fR(1),
 122 \fBsd-event\fR(3),
 123 \fBsd_event_new\fR(3),
 124 \fBsd_event_add_time\fR(3),
 125 \fBsd_event_add_signal\fR(3),
 126 \fBsd_event_add_defer\fR(3),
 127 \fBsd_event_source_set_enabled\fR(3)