Helper library

Dealing with SUID helper processes. More...

Collaboration diagram for Helper library:

Typedefs
typedef void(*	GNUNET_HELPER_ExceptionCallback) (void *cls)
	Callback that will be called when the helper process dies.
typedef void(*	GNUNET_HELPER_Continuation) (void *cls, enum GNUNET_GenericReturnValue result)
	Continuation function.

Functions
struct GNUNET_HELPER_Handle *	GNUNET_HELPER_start (const struct GNUNET_OS_ProjectData *pd, int with_control_pipe, const char *binary_name, char *const binary_argv[], GNUNET_MessageTokenizerCallback cb, GNUNET_HELPER_ExceptionCallback exp_cb, void *cb_cls)
	Starts a helper and begins reading from it.
enum GNUNET_GenericReturnValue	GNUNET_HELPER_kill (struct GNUNET_HELPER_Handle *h, int soft_kill)
	Sends termination signal to the helper process.
enum GNUNET_GenericReturnValue	GNUNET_HELPER_wait (struct GNUNET_HELPER_Handle *h)
	Reap the helper process.
void	GNUNET_HELPER_destroy (struct GNUNET_HELPER_Handle *h)
	Free's the resources occupied by the helper handle.
void	GNUNET_HELPER_stop (struct GNUNET_HELPER_Handle *h, int soft_kill)
	Kills the helper, closes the pipe, frees the handle and calls wait() on the helper process.
struct GNUNET_HELPER_SendHandle *	GNUNET_HELPER_send (struct GNUNET_HELPER_Handle *h, const struct GNUNET_MessageHeader *msg, bool can_drop, GNUNET_HELPER_Continuation cont, void *cont_cls)
	Send an message to the helper.
void	GNUNET_HELPER_send_cancel (struct GNUNET_HELPER_SendHandle *sh)
	Cancel a GNUNET_HELPER_send operation.

Detailed Description

Dealing with SUID helper processes.

Provides an API for dealing with (SUID) helper processes that communicate via GNUNET_MessageHeaders on STDIN/STDOUT.

Typedef Documentation

GNUNET_HELPER_ExceptionCallback

typedef void(* GNUNET_HELPER_ExceptionCallback) (void *cls)

Callback that will be called when the helper process dies.

This is not called when the helper process is stopped using GNUNET_HELPER_stop()

Parameters

cls	the closure from GNUNET_HELPER_start()

Definition at line 64 of file gnunet_helper_lib.h.

GNUNET_HELPER_Continuation

typedef void(* GNUNET_HELPER_Continuation) (void *cls, enum GNUNET_GenericReturnValue result)

Continuation function.

Parameters

cls	closure
result	GNUNET_OK on success, GNUNET_NO if helper process died GNUNET_SYSERR during GNUNET_HELPER_destroy

Definition at line 151 of file gnunet_helper_lib.h.

Function Documentation

GNUNET_HELPER_start()

struct GNUNET_HELPER_Handle * GNUNET_HELPER_start	(	const struct GNUNET_OS_ProjectData *	pd,
		int	with_control_pipe,
		const char *	binary_name,
		char *const	binary_argv[],
		GNUNET_MessageTokenizerCallback	cb,
		GNUNET_HELPER_ExceptionCallback	exp_cb,
		void *	cb_cls
	)

Starts a helper and begins reading from it.

The helper process is restarted when it dies except when it is stopped using GNUNET_HELPER_stop() or when the exp_cb callback is not NULL.

Parameters

pd	project data to use to determine paths
with_control_pipe	does the helper support the use of a control pipe for signalling?
binary_name	name of the binary to run
binary_argv	NULL-terminated list of arguments to give when starting the binary (this argument must not be modified by the client for the lifetime of the helper handle)
cb	function to call if we get messages from the helper
exp_cb	the exception callback to call. Set this to NULL if the helper process has to be restarted automatically when it dies/crashes
cb_cls	closure for the above callbacks

Returns

the new Handle, NULL on error

Definition at line 484 of file helper.c.

{
  struct GNUNET_HELPER_Handle *h;
  unsigned int c;
 
  h = GNUNET_new (struct GNUNET_HELPER_Handle);
  h->with_control_pipe = with_control_pipe;
  /* Lookup in libexec path only if we are starting gnunet helpers */
  if (NULL != strstr (binary_name, "gnunet"))
    h->binary_name = GNUNET_OS_get_libexec_binary_path (pd,
                                                        binary_name);
  else
    h->binary_name = GNUNET_strdup (binary_name);
  for (c = 0; NULL != binary_argv[c]; c++)
    ;
  h->binary_argv = GNUNET_malloc (sizeof(char *) * (c + 1));
  for (c = 0; NULL != binary_argv[c]; c++)
    h->binary_argv[c] = GNUNET_strdup (binary_argv[c]);
  h->binary_argv[c] = NULL;
  h->cb_cls = cb_cls;
  if (NULL != cb)
    h->mst = GNUNET_MST_create (cb, h->cb_cls);
  h->exp_cb = exp_cb;
  h->retry_back_off = 0;
  start_helper (h);
  return h;
}

References GNUNET_HELPER_Handle::binary_argv, GNUNET_HELPER_Handle::binary_name, GNUNET_HELPER_Handle::cb_cls, exp_cb(), GNUNET_malloc, GNUNET_MST_create(), GNUNET_new, GNUNET_OS_get_libexec_binary_path(), GNUNET_strdup, h, start_helper(), and GNUNET_HELPER_Handle::with_control_pipe.

Referenced by enable(), enable(), GNUNET_FS_directory_scan_start(), run(), run(), run(), and start_helper().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_HELPER_kill()

enum GNUNET_GenericReturnValue GNUNET_HELPER_kill	(	struct GNUNET_HELPER_Handle *	h,
		int	soft_kill
	)

Sends termination signal to the helper process.

The helper process is not reaped; call GNUNET_HELPER_wait() for reaping the dead helper process.

Parameters

h	the helper handle
soft_kill	if GNUNET_YES, signals termination by closing the helper's stdin; GNUNET_NO to signal termination by sending SIGTERM to helper

Returns

GNUNET_OK on success; GNUNET_SYSERR on error

Definition at line 166 of file helper.c.

{
  struct GNUNET_HELPER_SendHandle *sh;
  int ret;
 
  while (NULL != (sh = h->sh_head))
  {
    GNUNET_CONTAINER_DLL_remove (h->sh_head, h->sh_tail, sh);
    if (NULL != sh->cont)
      sh->cont (sh->cont_cls, GNUNET_NO);
    GNUNET_free (sh);
  }
  if (NULL != h->restart_task)
  {
    GNUNET_SCHEDULER_cancel (h->restart_task);
    h->restart_task = NULL;
  }
  if (NULL != h->read_task)
  {
    GNUNET_SCHEDULER_cancel (h->read_task);
    h->read_task = NULL;
  }
  if (NULL == h->helper_proc)
    return GNUNET_SYSERR;
  if (GNUNET_YES == soft_kill)
  {
    /* soft-kill only possible with pipes */
    GNUNET_assert (NULL != h->helper_in);
    ret = GNUNET_DISK_pipe_close (h->helper_in);
    h->helper_in = NULL;
    h->fh_to_helper = NULL;
    return ret;
  }
  if (GNUNET_OK !=
      GNUNET_process_kill (h->helper_proc,
                           GNUNET_TERM_SIG))
    return GNUNET_SYSERR;
  return GNUNET_OK;
}

References GNUNET_assert, GNUNET_CONTAINER_DLL_remove, GNUNET_DISK_pipe_close(), GNUNET_free, GNUNET_NO, GNUNET_OK, GNUNET_process_kill(), GNUNET_SCHEDULER_cancel(), GNUNET_SYSERR, GNUNET_TERM_SIG, GNUNET_YES, h, ret, and sh.

Referenced by cleanup(), disable(), disable(), and stop_helper().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_HELPER_wait()

enum GNUNET_GenericReturnValue GNUNET_HELPER_wait

(

struct GNUNET_HELPER_Handle *

h

)

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

Parameters

h	the helper handle

Returns

GNUNET_OK on success; GNUNET_SYSERR on error

Definition at line 208 of file helper.c.

{
  struct GNUNET_HELPER_SendHandle *sh;
  enum GNUNET_GenericReturnValue ret;
 
  ret = GNUNET_SYSERR;
  if (NULL != h->helper_proc)
  {
    ret = GNUNET_process_wait (h->helper_proc,
                               true,
                               NULL,
                               NULL);
    GNUNET_process_destroy (h->helper_proc);
    h->helper_proc = NULL;
  }
  if (NULL != h->read_task)
  {
    GNUNET_SCHEDULER_cancel (h->read_task);
    h->read_task = NULL;
  }
  if (NULL != h->write_task)
  {
    GNUNET_SCHEDULER_cancel (h->write_task);
    h->write_task = NULL;
  }
  if (NULL != h->helper_in)
  {
    GNUNET_DISK_pipe_close (h->helper_in);
    h->helper_in = NULL;
    h->fh_to_helper = NULL;
  }
  if (NULL != h->helper_out)
  {
    GNUNET_DISK_pipe_close (h->helper_out);
    h->helper_out = NULL;
    h->fh_from_helper = NULL;
  }
  while (NULL != (sh = h->sh_head))
  {
    GNUNET_CONTAINER_DLL_remove (h->sh_head,
                                 h->sh_tail,
                                 sh);
    if (NULL != sh->cont)
      sh->cont (sh->cont_cls,
                GNUNET_NO);
    GNUNET_free (sh);
  }
  /* purge MST buffer */
  if (NULL != h->mst)
    (void) GNUNET_MST_from_buffer (h->mst,
                                   NULL,
                                   0,
                                   GNUNET_YES,
                                   GNUNET_NO);
  return ret;
}

References GNUNET_CONTAINER_DLL_remove, GNUNET_DISK_pipe_close(), GNUNET_free, GNUNET_MST_from_buffer(), GNUNET_NO, GNUNET_process_destroy(), GNUNET_process_wait(), GNUNET_SCHEDULER_cancel(), GNUNET_SYSERR, GNUNET_YES, h, ret, and sh.

Referenced by cleanup(), and stop_helper().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_HELPER_destroy()

void GNUNET_HELPER_destroy

(

struct GNUNET_HELPER_Handle *

h

)

Free's the resources occupied by the helper handle.

Parameters

h	the helper handle to free

Definition at line 525 of file helper.c.

{
  unsigned int c;
  struct GNUNET_HELPER_SendHandle *sh;
 
  if (NULL != h->write_task)
  {
    GNUNET_SCHEDULER_cancel (h->write_task);
    h->write_task = NULL;
  }
  GNUNET_assert (NULL == h->read_task);
  GNUNET_assert (NULL == h->restart_task);
  while (NULL != (sh = h->sh_head))
  {
    GNUNET_CONTAINER_DLL_remove (h->sh_head, h->sh_tail, sh);
    if (NULL != sh->cont)
      sh->cont (sh->cont_cls, GNUNET_SYSERR);
    GNUNET_free (sh);
  }
  if (NULL != h->mst)
    GNUNET_MST_destroy (h->mst);
  GNUNET_free (h->binary_name);
  for (c = 0; h->binary_argv[c] != NULL; c++)
    GNUNET_free (h->binary_argv[c]);
  GNUNET_free (h->binary_argv);
  GNUNET_free (h);
}

References GNUNET_assert, GNUNET_CONTAINER_DLL_remove, GNUNET_free, GNUNET_MST_destroy(), GNUNET_SCHEDULER_cancel(), GNUNET_SYSERR, h, and sh.

Referenced by disable(), disable(), and GNUNET_HELPER_stop().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_HELPER_stop()

void GNUNET_HELPER_stop	(	struct GNUNET_HELPER_Handle *	h,
		int	soft_kill
	)

Kills the helper, closes the pipe, frees the handle and calls wait() on the helper process.

Parameters

h	handle to helper to stop
soft_kill	if GNUNET_YES, signals termination by closing the helper's stdin; GNUNET_NO to signal termination by sending SIGTERM to helper

Kills the helper, closes the pipe, frees the handle and calls wait() on the helper process.

Parameters

h	handle to helper to stop
soft_kill	if GNUNET_YES, signals termination by closing the helper's stdin; GNUNET_NO to signal termination by sending SIGTERM to helper

Definition at line 562 of file helper.c.

{
  h->exp_cb = NULL;
  stop_helper (h, soft_kill);
  GNUNET_HELPER_destroy (h);
}

References GNUNET_HELPER_destroy(), h, and stop_helper().

Referenced by cleanup(), cleanup_task(), finish_scan(), GNUNET_FS_directory_scan_abort(), handle_helper_local_finished(), helper_read(), helper_write(), and netjail_exec_cleanup().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_HELPER_send()

struct GNUNET_HELPER_SendHandle * GNUNET_HELPER_send	(	struct GNUNET_HELPER_Handle *	h,
		const struct GNUNET_MessageHeader *	msg,
		bool	can_drop,
		GNUNET_HELPER_Continuation	cont,
		void *	cont_cls
	)

Send an message to the helper.

Parameters

h	helper to send message to
msg	message to send
can_drop	can the message be dropped if there is already one in the queue?
cont	continuation to run once the message is out (GNUNET_OK on success, GNUNET_NO if the helper process died, GNUNET_SYSERR during GNUNET_HELPER_destroy).
cont_cls	closure for cont

Returns

NULL if the message was dropped, otherwise handle to cancel cont (actual transmission may not be abortable)

Definition at line 639 of file helper.c.

{
  struct GNUNET_HELPER_SendHandle *sh;
  uint16_t mlen;
 
  if (NULL == h->fh_to_helper)
    return NULL;
  if (can_drop && (NULL != h->sh_head))
    return NULL;
  mlen = ntohs (msg->size);
  sh = GNUNET_malloc (sizeof(struct GNUNET_HELPER_SendHandle) + mlen);
  sh->msg = (const struct GNUNET_MessageHeader *) &sh[1];
  GNUNET_memcpy (&sh[1], msg, mlen);
  sh->h = h;
  sh->cont = cont;
  sh->cont_cls = cont_cls;
  GNUNET_CONTAINER_DLL_insert_tail (h->sh_head, h->sh_tail, sh);
  if (NULL == h->write_task)
    h->write_task =
      GNUNET_SCHEDULER_add_write_file (GNUNET_TIME_UNIT_FOREVER_REL,
                                       h->fh_to_helper,
                                       &helper_write,
                                       h);
 
  return sh;
}

References GNUNET_CONTAINER_DLL_insert_tail, GNUNET_malloc, GNUNET_memcpy, GNUNET_SCHEDULER_add_write_file(), GNUNET_TIME_UNIT_FOREVER_REL, h, helper_write(), msg, sh, and GNUNET_MessageHeader::size.

Referenced by GNUNET_TESTING_loop_notify_children_(), handle_icmp_back(), handle_tcp_back(), handle_udp_back(), play(), request_done(), send_icmp_packet_via_tun(), send_start_messages(), send_tcp_packet_via_tun(), and send_udp_packet_via_tun().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_HELPER_send_cancel()

void GNUNET_HELPER_send_cancel

(

struct GNUNET_HELPER_SendHandle *

sh

)

Cancel a GNUNET_HELPER_send operation.

If possible, transmitting the message is also aborted, but at least 'cont' won't be called.

Parameters

sh	operation to cancel

Definition at line 679 of file helper.c.

{
  struct GNUNET_HELPER_Handle *h = sh->h;
 
  sh->cont = NULL;
  sh->cont_cls = NULL;
  if (0 == sh->wpos)
  {
    GNUNET_CONTAINER_DLL_remove (h->sh_head, h->sh_tail, sh);
    GNUNET_free (sh);
    if (NULL == h->sh_head)
    {
      GNUNET_SCHEDULER_cancel (h->write_task);
      h->write_task = NULL;
    }
  }
}

References GNUNET_CONTAINER_DLL_remove, GNUNET_free, GNUNET_SCHEDULER_cancel(), h, and sh.

Referenced by finish_test().

Here is the call graph for this function:

Here is the caller graph for this function: