pfopen.h File Reference

Types and definitions for child process Open + I/O redirection. More...

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

Go to the source code of this file.

Data Structures
struct	_pfile_
Defines
#define	PF_OUT(pf)   ((pf)->fp[0])
	Returns pf's STDOUT FILE pointer.
#define	PF_ERR(pf)   ((pf)->fp[1])
	Returns pf's STDERR FILE pointer.
#define	PF_IN(pf)   ((pf)->fp[2])
	Returns pf's STDIN FILE pointer.
Typedefs
typedef struct _pfile_	PFILE
Functions
PFILE *	pfopen (const char *cmdstring, const char *type)
	Open a child process whose STDIO is redirected to the parent.
int	pfclose (PFILE *pfile)
	Close an existing PFILE object.
int	pfkill (PFILE *pfile, int sig)
	Kill a set of processes associated with an existing PFILE object.

---

Detailed Description

Types and definitions for child process Open + I/O redirection.

A much enhanced alternative to popen(3p) that allows reading from both stdout and stderr of the child shell process. Additionally, both read and write are supported simultanteously for full communication to the child on its STDIO channels.

This module works similarly to popen(3p) except that it returns a PFILE * instead of the standard FILE *. This allows us to supply multiple I/O streams for reading. It also contains the pid of the child process, which is used by the complementary pfclose() function for shutting down the pipe and pfkill for killing the child process and all of its process group members.

The other difference is that when using the PFILE * with the standard I/O functions (e.g., fgets, fprintf, etc.) you must use the supplied macros in order to obtain the underlying FILE * for use with the stdio functions.

These macros are:

PF_IN(p) - Retrieves FILE * handle for writing to child process' stdin PF_OUT(p) - Retrieves FILE * handle for reading from child process' stdout PF_ERR(p) - Retrieves FILE * handle for reading from child process' stderr

Author:

Robert W. Ingraham (dnx-devel@lists.sourceforge.net)

Attention:

Please submit patches to http://dnx.sourceforge.net

Definition in file pfopen.h.

---

Define Documentation

#define PF_ERR

(

pf

)

((pf)->fp[1])

Returns pf's STDERR FILE pointer.

Definition at line 58 of file pfopen.h.

Referenced by dnxPluginExternal().

#define PF_IN

(

pf

)

((pf)->fp[2])

Returns pf's STDIN FILE pointer.

Definition at line 59 of file pfopen.h.

#define PF_OUT

(

pf

)

((pf)->fp[0])

Returns pf's STDOUT FILE pointer.

Definition at line 57 of file pfopen.h.

Referenced by dnxPluginExternal().

---

Typedef Documentation

typedef struct _pfile_ PFILE

---

Function Documentation

int pfclose

(

PFILE *

pfile

)

Close an existing PFILE object.

Closes all open pipe handles, and then waits for the associated child process to die, returning the status value of the child process.

Parameters:

[in]

pfile

- the process pipe to be closed.

Returns:

The value of the waitpid system call's stat_loc parameter, or the status of the child processed waited for using the waitpid system call.

Note:

Because the return value of this routine is the stat_loc value of the waitpid system call, any of the W* macros defined for use on this value by the system may be used to query the status of the associated child process.

Definition at line 212 of file pfopen.c.

References _pfile_::fp, _pfile_::pid, and xfree.

Referenced by dnxPluginExternal().

int pfkill	(	PFILE *	pfile,
		int	sig
	)

Kill a set of processes associated with an existing PFILE object.

Parameters:

[in]	pfile	- the pipe representing the process to be killed.
[in]	sig	- the signal to send the process.

Returns:

Zero on success, or -1 on error, and the global errno is set.

Definition at line 247 of file pfopen.c.

References _pfile_::pid.

Referenced by dnxPluginExternal().

PFILE* pfopen	(	const char *	cmdstring,
		const char *	type
	)

Open a child process whose STDIO is redirected to the parent.

The STDOUT, STDERR, and (optionally) STDIN file handles for the child process are available to the parent (the calling process) to be used in any appropriate manner.

The only allowable modes for the pipe are 'read' and 'write' as specified by the type parameter in the form of a single 'r' or 'w' character string. A 'r' channel is read-only and can only be used to gather data from the child process. A 'w' channel can also be used to send data to the child process.

We use (up to) three pipes for communication. According to POSIX.1g it's not specified whether you can write to the read end of a pipe, or vice-versa; pipes are defined as half-duplex. Thus, we need to open a separate pipe (pair of file descriptors) for each channel. While full- duplex pipes are probably available everywhere, it's not in the spec, so it's not portable.

• First Pipe:
  • pfd[0] The parent reads stdout data from the child.
  • pfd[1] The child writes stdout data to the parent.
• Second Pipe:
  • pfd[2] The parent reads stderr data from the child.
  • pfd[3] The child writes stderr data to the parent.
• Third Pipe (optional - *type == 'w'):
  • pfd[4] The child reads stdin data from the parent.
  • pfd[5] The parent writes stdin data to the child.

Parameters:

[in]	cmdstring	- the command string executed as a child process.
[in]	type	- the file type string used when opening the I/O channel to the child process.

Returns:

A newly allocated PFILE object reference. This object may be queried or closed using the other calls defined in this module. If this routine returns 0, it indicates an error and errno is set appropriately.

Definition at line 93 of file pfopen.c.

References elemcount, _pfile_::fp, _pfile_::pid, xcalloc, and xfree.

Referenced by dnxPluginExternal().