filter.h File Reference

Pass files through external commands (filters) More...

#include <stdio.h>
#include <sys/types.h>

Include dependency graph for filter.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	EXEC_SHELL   "/bin/sh"
	Default shell to use for executing commands.

Functions
pid_t	filter_create (const char *cmd, FILE **fp_in, FILE **fp_out, FILE **fp_err, char **envlist)
	Set up filter program.
pid_t	filter_create_fd (const char *cmd, FILE **fp_in, FILE **fp_out, FILE **fp_err, int fdin, int fdout, int fderr, char **envlist)
	Run a command on a pipe (optionally connect stdin/stdout)
int	filter_wait (pid_t pid)
	Wait for the exit of a process and return its status.

Detailed Description

Pass files through external commands (filters)

Authors

• Richard Russon

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file filter.h.

Macro Definition Documentation

EXEC_SHELL

#define EXEC_SHELL   "/bin/sh"

Default shell to use for executing commands.

Definition at line 30 of file filter.h.

Function Documentation

filter_create()

pid_t filter_create	(	const char *	cmd,
		FILE **	fp_in,
		FILE **	fp_out,
		FILE **	fp_err,
		char **	envlist )

Set up filter program.

Parameters

[in]	cmd	Command string
[out]	fp_in	FILE pointer of stdin
[out]	fp_out	FILE pointer of stdout
[out]	fp_err	FILE pointer of stderr
[in]	envlist	Environment variables

Return values

num	PID of filter

Definition at line 220 of file filter.c.

{
  return filter_create_fd(cmd, fp_in, fp_out, fp_err, -1, -1, -1, envlist);
}

Here is the call graph for this function:

Here is the caller graph for this function:

filter_create_fd()

pid_t filter_create_fd	(	const char *	cmd,
		FILE **	fp_in,
		FILE **	fp_out,
		FILE **	fp_err,
		int	fdin,
		int	fdout,
		int	fderr,
		char **	envlist )

Run a command on a pipe (optionally connect stdin/stdout)

Parameters

[in]	cmd	Command line to invoke using sh -c
[out]	fp_in	File stream pointing to stdin for the command process, can be NULL
[out]	fp_out	File stream pointing to stdout for the command process, can be NULL
[out]	fp_err	File stream pointing to stderr for the command process, can be NULL
[in]	fdin	If fp_in is NULL and fdin is not -1 then fdin will be used as stdin for the command process
[in]	fdout	If fp_out is NULL and fdout is not -1 then fdout will be used as stdout for the command process
[in]	fderr	If fp_err is NULL and fderr is not -1 then fderr will be used as stderr for the command process
[in]	envlist	Environment variables

Return values

num	PID of the created process
-1	Error creating pipes or forking

This function provides multiple mechanisms to handle IO sharing for the command process. File streams are prioritized over file descriptors if present.

filter_create_fd(commandline, NULL, NULL, NULL, -1, -1, -1);

Additionally, fp_in, fp_out, and fp_err will point to FILE* streams representing the processes stdin, stdout, and stderr.

Definition at line 62 of file filter.c.

{
  int pin[2] = { 0 };
  int pout[2] = { 0 };
  int perr[2] = { 0 };
  int pid;
 
  /* Create pipes for each requested I/O stream (stdin, stdout, stderr).
   * On failure, clean up any already-created pipes before returning. */
  if (fp_in)
  {
    *fp_in = NULL;
    if (pipe(pin) == -1)
      return -1;
  }
 
  if (fp_out)
  {
    *fp_out = NULL;
    if (pipe(pout) == -1)
    {
      if (fp_in)
      {
        close(pin[0]);
        close(pin[1]);
      }
      return -1;
    }
  }
 
  if (fp_err)
  {
    *fp_err = NULL;
    if (pipe(perr) == -1)
    {
      if (fp_in)
      {
        close(pin[0]);
        close(pin[1]);
      }
      if (fp_out)
      {
        close(pout[0]);
        close(pout[1]);
      }
      return -1;
    }
  }
 
  /* Block signals around fork to prevent child from inheriting pending signals */
  mutt_sig_block_system();
 
  pid = fork();
  if (pid == 0)
  {
    /* Child process: redirect pipe ends to stdin/stdout/stderr via dup2(),
     * or use the caller-supplied file descriptors as fallback */
    mutt_sig_unblock_system(false);
    mutt_sig_reset_child_signals();
 
    if (fp_in)
    {
      close(pin[1]);
      dup2(pin[0], 0);
      close(pin[0]);
    }
    else if (fdin != -1)
    {
      dup2(fdin, 0);
      close(fdin);
    }
 
    if (fp_out)
    {
      close(pout[0]);
      dup2(pout[1], 1);
      close(pout[1]);
    }
    else if (fdout != -1)
    {
      dup2(fdout, 1);
      close(fdout);
    }
 
    if (fp_err)
    {
      close(perr[0]);
      dup2(perr[1], 2);
      close(perr[1]);
    }
    else if (fderr != -1)
    {
      dup2(fderr, 2);
      close(fderr);
    }
 
    execle(EXEC_SHELL, "sh", "-c", cmd, NULL, envlist);
    _exit(127);
  }
  else if (pid == -1)
  {
    /* Fork failed: clean up all pipe file descriptors */
    mutt_sig_unblock_system(true);
 
    if (fp_in)
    {
      close(pin[0]);
      close(pin[1]);
    }
 
    if (fp_out)
    {
      close(pout[0]);
      close(pout[1]);
    }
 
    if (fp_err)
    {
      close(perr[0]);
      close(perr[1]);
    }
 
    return -1;
  }
 
  /* Parent process: close the child's end of each pipe and wrap
   * the parent's end in a FILE stream for the caller */
  if (fp_out)
  {
    close(pout[1]);
    *fp_out = fdopen(pout[0], "r");
  }
 
  if (fp_in)
  {
    close(pin[0]);
    *fp_in = fdopen(pin[1], "w");
  }
 
  if (fp_err)
  {
    close(perr[1]);
    *fp_err = fdopen(perr[0], "r");
  }
 
  return pid;
}

Here is the call graph for this function:

Here is the caller graph for this function:

filter_wait()

int filter_wait

(

pid_t

pid

)

Wait for the exit of a process and return its status.

Parameters

pid	Process id of the process to wait for

Return values

num	Exit status of the process identified by pid
-1	Error

Definition at line 231 of file filter.c.

{
  int rc = 0;
 
  waitpid(pid, &rc, 0);
  mutt_sig_unblock_system(true);
  rc = WIFEXITED(rc) ? WEXITSTATUS(rc) : -1;
 
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function: