use -Wl on -no-undefined as it is a linker option:

[oweals/gnunet.git] / src / include / gnunet_helper_lib.h

diff --git a/src/include/gnunet_helper_lib.h b/src/include/gnunet_helper_lib.h
index 7f43f1a6493ee0363d348c0640aa750df44d8b2e..9c4c0c9864981fd50f35baa54e7e4b438d6763f7 100644 (file)
--- a/src/include/gnunet_helper_lib.h
+++ b/src/include/gnunet_helper_lib.h
@@ -20,7 +20,8 @@
 
 /**
  * @file include/gnunet_helper_lib.h
- * @brief API for dealing with (SUID) helper processes that communicate via GNUNET_MessageHeaders on stdin/stdout
+ * @brief API for dealing with (SUID) helper processes that communicate via
+ *          GNUNET_MessageHeaders on stdin/stdout
  * @author Philipp Toelke
  * @author Christian Grothoff
  */
@@ -72,21 +73,58 @@ GNUNET_HELPER_start (int with_control_pipe,
 
 
 /**
- * Kills the helper, closes the pipe and frees the handle
+ * Sends termination signal to the helper process.  The helper process is not
+ * reaped; call GNUNET_HELPER_wait() for reaping the dead helper process.
+ *
+ * @param h the helper handle
+ * @param soft_kill if #GNUNET_YES, signals termination by closing the helper's
+ *          stdin; #GNUNET_NO to signal termination by sending SIGTERM to helper
+ * @return #GNUNET_OK on success; #GNUNET_SYSERR on error
+ */
+int
+GNUNET_HELPER_kill (struct GNUNET_HELPER_Handle *h, int soft_kill);
+
+
+/**
+ * Reap the helper process.  This call is blocking (!).  The helper process
+ * should either be sent a termination signal before or should be dead before
+ * calling this function
+ *
+ * @param h the helper handle
+ * @return #GNUNET_OK on success; #GNUNET_SYSERR on error
+ */
+int
+GNUNET_HELPER_wait (struct GNUNET_HELPER_Handle *h);
+
+
+/**
+ * Free's the resources occupied by the helper handle
+ *
+ * @param h the helper handle to free
+ */
+void
+GNUNET_HELPER_destroy (struct GNUNET_HELPER_Handle *h);
+
+
+/**
+ * Kills the helper, closes the pipe, frees the handle and calls wait() on the
+ * helper process
  *
  * @param h handle to helper to stop
+ * @param soft_kill if #GNUNET_YES, signals termination by closing the helper's
+ *          stdin; #GNUNET_NO to signal termination by sending SIGTERM to helper
  */
 void
-GNUNET_HELPER_stop (struct GNUNET_HELPER_Handle *h);
+GNUNET_HELPER_stop (struct GNUNET_HELPER_Handle *h, int soft_kill);
 
 
 /**
  * Continuation function.
- * 
+ *
  * @param cls closure
- * @param result GNUNET_OK on success,
- *               GNUNET_NO if helper process died
- *               GNUNET_SYSERR during GNUNET_HELPER_stop
+ * @param result #GNUNET_OK on success,
+ *               #GNUNET_NO if helper process died
+ *               #GNUNET_SYSERR during GNUNET_HELPER_destroy
  */
 typedef void (*GNUNET_HELPER_Continuation)(void *cls,
                                           int result);
@@ -104,14 +142,15 @@ struct GNUNET_HELPER_SendHandle;
  * @param h helper to send message to
  * @param msg message to send
  * @param can_drop can the message be dropped if there is already one in the queue?
- * @param cont continuation to run once the message is out
- * @param cont_cls closure for 'cont'
- * @return NULL if the message was dropped, 
- *         otherwise handle to cancel *cont* (actual transmission may
+ * @param cont continuation to run once the message is out (#GNUNET_OK on succees, #GNUNET_NO
+ *             if the helper process died, #GNUNET_SYSERR during #GNUNET_HELPER_destroy).
+ * @param cont_cls closure for @a cont
+ * @return NULL if the message was dropped,
+ *         otherwise handle to cancel @a cont (actual transmission may
  *         not be abortable)
  */
 struct GNUNET_HELPER_SendHandle *
-GNUNET_HELPER_send (struct GNUNET_HELPER_Handle *h, 
+GNUNET_HELPER_send (struct GNUNET_HELPER_Handle *h,
                    const struct GNUNET_MessageHeader *msg,
                    int can_drop,
                    GNUNET_HELPER_Continuation cont,
@@ -119,13 +158,13 @@ GNUNET_HELPER_send (struct GNUNET_HELPER_Handle *h,
 
 
 /**
- * Cancel a 'send' operation.  If possible, transmitting the
- * message is also aborted, but at least 'cont' won't be
- * called.
+ * Cancel a #GNUNET_HELPER_send operation.  If possible, transmitting
+ * the message is also aborted, but at least 'cont' won't be called.
  *
  * @param sh operation to cancel
  */
 void
 GNUNET_HELPER_send_cancel (struct GNUNET_HELPER_SendHandle *sh);
 
-#endif /* end of include guard: GNUNET_HELPER_LIB_H */
+#endif
+/* end of include guard: GNUNET_HELPER_LIB_H */