gnunet_helper_lib.h (6167B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2011, 2012 Christian Grothoff 4 5 GNUnet is free software: you can redistribute it and/or modify it 6 under the terms of the GNU Affero General Public License as published 7 by the Free Software Foundation, either version 3 of the License, 8 or (at your option) any later version. 9 10 GNUnet is distributed in the hope that it will be useful, but 11 WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Affero General Public License for more details. 14 15 You should have received a copy of the GNU Affero General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 /** 22 * @addtogroup libgnunetutil 23 * Multi-function utilities library for GNUnet programs 24 * @{ 25 * 26 * @author Philipp Toelke 27 * @author Christian Grothoff 28 * 29 * @file 30 * API for dealing with SUID helper processes 31 * 32 * @defgroup helper Helper library 33 * Dealing with SUID helper processes. 34 * 35 * Provides an API for dealing with (SUID) helper processes 36 * that communicate via GNUNET_MessageHeaders on STDIN/STDOUT. 37 * 38 * @{ 39 */ 40 41 #if ! defined (__GNUNET_UTIL_LIB_H_INSIDE__) 42 #error "Only <gnunet_util_lib.h> can be included directly." 43 #endif 44 45 #ifndef GNUNET_HELPER_LIB_H 46 #define GNUNET_HELPER_LIB_H 47 48 49 #include "gnunet_mst_lib.h" 50 51 52 /** 53 * The handle to a helper process. 54 */ 55 struct GNUNET_HELPER_Handle; 56 57 58 /** 59 * Callback that will be called when the helper process dies. This is not called 60 * when the helper process is stopped using GNUNET_HELPER_stop() 61 * 62 * @param cls the closure from GNUNET_HELPER_start() 63 */ 64 typedef void 65 (*GNUNET_HELPER_ExceptionCallback) (void *cls); 66 67 68 /** 69 * Starts a helper and begins reading from it. The helper process is 70 * restarted when it dies except when it is stopped using GNUNET_HELPER_stop() 71 * or when the exp_cb callback is not NULL. 72 * 73 * @param pd project data to use to determine paths 74 * @param with_control_pipe does the helper support the use of a control pipe for signalling? 75 * @param binary_name name of the binary to run 76 * @param binary_argv NULL-terminated list of arguments to give when starting the binary (this 77 * argument must not be modified by the client for 78 * the lifetime of the helper handle) 79 * @param cb function to call if we get messages from the helper 80 * @param exp_cb the exception callback to call. Set this to NULL if the helper 81 * process has to be restarted automatically when it dies/crashes 82 * @param cb_cls closure for the above callbacks 83 * @return the new Handle, NULL on error 84 */ 85 struct GNUNET_HELPER_Handle * 86 GNUNET_HELPER_start (const struct GNUNET_OS_ProjectData *pd, 87 int with_control_pipe, 88 const char *binary_name, 89 char *const binary_argv[], 90 GNUNET_MessageTokenizerCallback cb, 91 GNUNET_HELPER_ExceptionCallback exp_cb, 92 void *cb_cls); 93 94 95 /** 96 * Sends termination signal to the helper process. The helper process is not 97 * reaped; call GNUNET_HELPER_wait() for reaping the dead helper process. 98 * 99 * @param h the helper handle 100 * @param soft_kill if #GNUNET_YES, signals termination by closing the helper's 101 * stdin; #GNUNET_NO to signal termination by sending SIGTERM to helper 102 * @return #GNUNET_OK on success; #GNUNET_SYSERR on error 103 */ 104 enum GNUNET_GenericReturnValue 105 GNUNET_HELPER_kill (struct GNUNET_HELPER_Handle *h, 106 int soft_kill); 107 108 109 /** 110 * Reap the helper process. This call is blocking (!). The helper process 111 * should either be sent a termination signal before or should be dead before 112 * calling this function 113 * 114 * @param h the helper handle 115 * @return #GNUNET_OK on success; #GNUNET_SYSERR on error 116 */ 117 enum GNUNET_GenericReturnValue 118 GNUNET_HELPER_wait (struct GNUNET_HELPER_Handle *h); 119 120 121 /** 122 * Free's the resources occupied by the helper handle 123 * 124 * @param h the helper handle to free 125 */ 126 void 127 GNUNET_HELPER_destroy (struct GNUNET_HELPER_Handle *h); 128 129 130 /** 131 * Kills the helper, closes the pipe, frees the handle and calls wait() on the 132 * helper process 133 * 134 * @param h handle to helper to stop 135 * @param soft_kill if #GNUNET_YES, signals termination by closing the helper's 136 * stdin; #GNUNET_NO to signal termination by sending SIGTERM to helper 137 */ 138 void 139 GNUNET_HELPER_stop (struct GNUNET_HELPER_Handle *h, 140 int soft_kill); 141 142 143 /** 144 * Continuation function. 145 * 146 * @param cls closure 147 * @param result #GNUNET_OK on success, 148 * #GNUNET_NO if helper process died 149 * #GNUNET_SYSERR during GNUNET_HELPER_destroy 150 */ 151 typedef void 152 (*GNUNET_HELPER_Continuation)( 153 void *cls, 154 enum GNUNET_GenericReturnValue result); 155 156 157 /** 158 * Handle to cancel 'send' 159 */ 160 struct GNUNET_HELPER_SendHandle; 161 162 163 /** 164 * Send an message to the helper. 165 * 166 * @param h helper to send message to 167 * @param msg message to send 168 * @param can_drop can the message be dropped if there is already one in the queue? 169 * @param cont continuation to run once the message is out (#GNUNET_OK on success, #GNUNET_NO 170 * if the helper process died, #GNUNET_SYSERR during #GNUNET_HELPER_destroy). 171 * @param cont_cls closure for @a cont 172 * @return NULL if the message was dropped, 173 * otherwise handle to cancel @a cont (actual transmission may 174 * not be abortable) 175 */ 176 struct GNUNET_HELPER_SendHandle * 177 GNUNET_HELPER_send (struct GNUNET_HELPER_Handle *h, 178 const struct GNUNET_MessageHeader *msg, 179 bool can_drop, 180 GNUNET_HELPER_Continuation cont, 181 void *cont_cls); 182 183 184 /** 185 * Cancel a #GNUNET_HELPER_send operation. If possible, transmitting 186 * the message is also aborted, but at least 'cont' won't be called. 187 * 188 * @param sh operation to cancel 189 */ 190 void 191 GNUNET_HELPER_send_cancel (struct GNUNET_HELPER_SendHandle *sh); 192 193 194 #endif 195 /* end of include guard: GNUNET_HELPER_LIB_H */ 196 197 /** @} */ /* end of group */ 198 199 /** @} */ /* end of group addition */