hawk/lib/hawk-pio.h

/*
    Copyright (c) 2006-2020 Chung, Hyung-Hwan. All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
    1. Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.

    THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
    OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
    IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
    THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef _HAWK_PIO_H_
#define _HAWK_PIO_H_

#include <hawk-cmn.h>
#include <hawk-tio.h>

/** \file 
 * This file defines a piped interface to a child process. You can execute
 * a child process, read and write to its stdin, stdout, stderr, and terminate
 * it. It provides more advanced interface than popen() and pclose().
 */

/**
 * The hawk_pio_flag_t defines enumerators to compose flags to hawk_pio_open().
 */
enum hawk_pio_flag_t
{
	/** enable text based I/O. */
	HAWK_PIO_TEXT          = (1 << 0),
	HAWK_PIO_IGNOREECERR = (1 << 1),
	HAWK_PIO_NOAUTOFLUSH   = (1 << 2),

	/** execute the command via a system shell 
	 * (/bin/sh on unix/linux, cmd.exe on windows and os2) */
	HAWK_PIO_SHELL         = (1 << 3),

	/** indicate that the command to hawk_pio_open() is a multi-byte string.
	 *  it is useful if #HAWK_OOCH_IS_UCH is defined. */
	HAWK_PIO_BCSTRCMD        = (1 << 4),

	/** don't attempt to close open file descriptors unknown to pio.
	 *  it is useful only on a unix-like systems where file descriptors
	 *  not set with FD_CLOEXEC are inherited by a child process.
	 *  you're advised to set this option if all normal file descriptors 
	 *  in your application are open with FD_CLOEXEC set. it can skip 
	 *  checking a bunch of file descriptors and arranging to close
	 *  them to prevent inheritance. */
	HAWK_PIO_NOCLOEXEC     = (1 << 5),

	/** indidate that the command to hawk_pio_open()/hawk_pio_init() is 
	 *  a pointer to a #hawk_pio_fnc_t structure. supported on unix/linux
	 *  only */
	HAWK_PIO_FNCCMD        = (1 << 6),

	/** write to stdin of a child process */
	HAWK_PIO_WRITEIN       = (1 << 8),
	/** read stdout of a child process */
	HAWK_PIO_READOUT       = (1 << 9),
	/** read stderr of a child process */
	HAWK_PIO_READERR       = (1 << 10),

	/** redirect stderr to stdout (2>&1, require #HAWK_PIO_READOUT) */
	HAWK_PIO_ERRTOOUT      = (1 << 11),
	/** redirect stdout to stderr (1>&2, require #HAWK_PIO_READERR) */
	HAWK_PIO_OUTTOERR      = (1 << 12),

	/** redirect stdin to the null device (</dev/null, <NUL) */
	HAWK_PIO_INTONUL       = (1 << 13),
	/** redirect stdin to the null device (>/dev/null, >NUL) */
	HAWK_PIO_ERRTONUL      = (1 << 14),
	/** redirect stderr to the null device (2>/dev/null, 2>NUL) */
	HAWK_PIO_OUTTONUL      = (1 << 15),

	/** drop stdin */
	HAWK_PIO_DROPIN        = (1 << 16), 
	/** drop stdout */
	HAWK_PIO_DROPOUT       = (1 << 17),
	/** drop stderr */
	HAWK_PIO_DROPERR       = (1 << 18),

	/** do not reread if read has been interrupted */
	HAWK_PIO_READNORETRY   = (1 << 21), 
	/** do not rewrite if write has been interrupted */
	HAWK_PIO_WRITENORETRY  = (1 << 22),
	/** return immediately from hawk_pio_wait() if a child has not exited */
	HAWK_PIO_WAITNOBLOCK   = (1 << 23),
	/** do not wait again if waitpid has been interrupted */
	HAWK_PIO_WAITNORETRY   = (1 << 24),

	/** put stdin to non-blocking mode (only on supported platforms) */
	HAWK_PIO_INNOBLOCK     = (1 << 25),
	/** put stdout to non-blocking mode (only on supported platforms)*/
	HAWK_PIO_OUTNOBLOCK    = (1 << 26),
	/** put stderr to non-blocking mode (only on supported platforms) */
	HAWK_PIO_ERRNOBLOCK    = (1 << 27)
};

/**
 * The hawk_pio_hid_t type defines pipe IDs established to a child process.
 */
enum hawk_pio_hid_t
{
	HAWK_PIO_IN  = 0, /**< stdin of a child process */ 
	HAWK_PIO_OUT = 1, /**< stdout of a child process */
	HAWK_PIO_ERR = 2  /**< stderr of a child process */
};
typedef enum hawk_pio_hid_t hawk_pio_hid_t;


typedef int (*hawk_pio_fncptr_t) (void* ctx);

/**
 * The hawk_pio_fnc_t type defines a structure to point to the function
 * executed in a child process when #HAWK_PIO_FNCCMD is specified.
 */
typedef struct hawk_pio_fnc_t hawk_pio_fnc_t;
struct hawk_pio_fnc_t
{
	hawk_pio_fncptr_t ptr;
	void* ctx;
};

#if defined(_WIN32)
	/* <winnt.h> => typedef PVOID HANDLE; */
	typedef void* hawk_pio_hnd_t; /**< defines a pipe handle type */
	typedef void* hawk_pio_pid_t; /**< defines a process handle type */
#	define  HAWK_PIO_HND_NIL ((hawk_pio_hnd_t)HAWK_NULL)
#	define  HAWK_PIO_PID_NIL ((hawk_pio_pid_t)HAWK_NULL)
#elif defined(__OS2__)
	/* <os2def.h> => typedef LHANDLE HFILE;
	                 typedef LHANDLE PID;
	                 typedef unsigned long LHANDLE; */
	typedef unsigned long hawk_pio_hnd_t; /**< defines a pipe handle type */
	typedef unsigned long hawk_pio_pid_t; /**< defined a process handle type */
#	define  HAWK_PIO_HND_NIL ((hawk_pio_hnd_t)-1)
#	define  HAWK_PIO_PID_NIL ((hawk_pio_pid_t)-1)
#elif defined(__DOS__)
	typedef int hawk_pio_hnd_t; /**< defines a pipe handle type */
	typedef int hawk_pio_pid_t; /**< defines a process handle type */
#	define  HAWK_PIO_HND_NIL ((hawk_pio_hnd_t)-1)
#	define  HAWK_PIO_PID_NIL ((hawk_pio_pid_t)-1)
#else
	typedef int hawk_pio_hnd_t; /**< defines a pipe handle type */
	typedef int hawk_pio_pid_t; /**< defines a process handle type */
#	define  HAWK_PIO_HND_NIL ((hawk_pio_hnd_t)-1)
#	define  HAWK_PIO_PID_NIL ((hawk_pio_pid_t)-1)
#endif

typedef struct hawk_pio_t hawk_pio_t;
typedef struct hawk_pio_pin_t hawk_pio_pin_t;

struct hawk_pio_pin_t
{
	hawk_pio_hnd_t handle;
	hawk_tio_t*    tio;
	hawk_pio_t*    self;	
};


/**
 * The hawk_pio_t type defines a structure to store status for piped I/O
 * to a child process. The hawk_pio_xxx() funtions are written around this
 * type. Do not change the value of each field directly. 
 */
struct hawk_pio_t
{
	hawk_gem_t*       gem;
	int               flags;  /**< options */
	hawk_pio_pid_t    child;   /**< handle to a child process */
	hawk_pio_pin_t    pin[3];
};

/** access the \a child field of the #hawk_pio_t structure */
#define HAWK_PIO_CHILD(pio)     ((pio)->child)
/** get the native handle from the #hawk_pio_t structure */
#define HAWK_PIO_HANDLE(pio,hid) ((pio)->pin[hid].handle)

#if defined(__cplusplus)
extern "C" {
#endif

/**
 * The hawk_pio_open() function executes a command \a cmd and establishes
 * pipes to it. #HAWK_PIO_SHELL causes the function to execute \a cmd via 
 * the default shell of an underlying system: /bin/sh on *nix, cmd.exe on win32.
 * On *nix systems, a full path to the command is needed if it is not specified.
 * If \a env is #HAWK_NULL, the environment of \a cmd inherits that of the 
 * calling process. If you want to pass an empty environment, you can pass
 * an empty \a env object with no items inserted. If #HAWK_PIO_BCSTRCMD is 
 * specified in \a flags, \a cmd is treated as a multi-byte string whose 
 * character type is #hawk_bch_t.
 * \return #hawk_pio_t object on success, #HAWK_NULL on failure
 */
HAWK_EXPORT hawk_pio_t* hawk_pio_open (
	hawk_gem_t*        gem,    /**< gem */
	hawk_oow_t         ext,    /**< extension size */
	const hawk_ooch_t* cmd,    /**< command to execute */
	int                flags   /**< 0 or a number OR'ed of the #hawk_pio_flag_t enumerators*/
);

/**
 * The hawk_pio_close() function closes pipes to a child process and waits for
 * the child process to exit.
 */
HAWK_EXPORT void hawk_pio_close (
	hawk_pio_t* pio /**< pio object */
);

/**
 * The hawk_pio_init() functions performs the same task as the hawk_pio_open()
 * except that you need to allocate a #hawk_pio_t structure and pass it to the
 * function.
 * \return 0 on success, -1 on failure
 */
HAWK_EXPORT int hawk_pio_init (
	hawk_pio_t*        pio,    /**< pio object */
	hawk_gem_t*        gem,    /**< gem */
	const hawk_ooch_t* cmd,    /**< command to execute */
	int                flags   /**< 0 or a number OR'ed of the #hawk_pio_flag_t enumerators*/
);

/**
 * The hawk_pio_fini() function performs the same task as hawk_pio_close()
 * except that it does not destroy a #hawk_pio_t structure pointed to by \a pio.
 */
HAWK_EXPORT void hawk_pio_fini (
	hawk_pio_t* pio /**< pio object */
);

#if defined(HAWK_HAVE_INLINE)
static HAWK_INLINE void* hawk_pio_getxtn (hawk_pio_t* pio) { return (void*)(pio + 1); }
#else
#define hawk_pio_getxtn(pio) ((void*)((hawk_pio_t*)(pio) + 1))
#endif

/**
 * The hawk_pio_getcmgr() function returns the current character manager.
 * It returns #HAWK_NULL is \a pio is not opened with #HAWK_PIO_TEXT.
 */
HAWK_EXPORT hawk_cmgr_t* hawk_pio_getcmgr (
	hawk_pio_t*    pio,
	hawk_pio_hid_t hid
);

/**
 * The hawk_pio_setcmgr() function changes the character manager to \a cmgr.
 * The character manager is used only if \a pio is opened with #HAWK_PIO_TEXT.
 */
HAWK_EXPORT void hawk_pio_setcmgr (
	hawk_pio_t*    pio,
	hawk_pio_hid_t hid,
	hawk_cmgr_t*   cmgr
);

/**
 * The hawk_pio_gethnd() function gets a pipe handle.
 * \return pipe handle
 */
HAWK_EXPORT hawk_pio_hnd_t hawk_pio_gethnd (
	const hawk_pio_t* pio, /**< pio object */
	hawk_pio_hid_t    hid  /**< handle ID */
);

/**
 * The hawk_pio_getchild() function gets a process handle.
 * \return process handle
 */
HAWK_EXPORT hawk_pio_pid_t hawk_pio_getchild (
	const hawk_pio_t* pio /**< pio object */
);

/**
 * The hawk_pio_read() fucntion reads at most \a size bytes/characters
 * and stores them to the buffer pointed to by \a buf.
 * \return -1 on failure, 0 on EOF, data length read on success
 */
HAWK_EXPORT hawk_ooi_t hawk_pio_read (
	hawk_pio_t*    pio,  /**< pio object */
	hawk_pio_hid_t hid,  /**< handle ID */
	void*          buf,  /**< buffer to fill */
	hawk_oow_t     size  /**< buffer size */
);

HAWK_EXPORT hawk_ooi_t hawk_pio_readbytes (
	hawk_pio_t*    pio,  /**< pio object */
	hawk_pio_hid_t hid,  /**< handle ID */
	void*          buf,  /**< buffer to fill */
	hawk_oow_t     size  /**< buffer size */
);


/**
 * The hawk_pio_write() function writes up \a size bytes/characters 
 * from the buffer pointed to by \a data. If #HAWK_PIO_TEXT is used 
 * and the \a size parameter is (hawk_oow_t)-1, the function treats 
 * the \a data parameter as a pointer to a null-terminated string.
 * (hawk_oow_t)-1 into \a size is not treated specially if #HAWK_PIO_TEXT
 * is not set.
 *
 * \return -1 on failure, data length written on success
 */
HAWK_EXPORT hawk_ooi_t hawk_pio_write (
	hawk_pio_t*    pio,   /**< pio object */
	hawk_pio_hid_t hid,   /**< handle ID */
	const void*    data,  /**< data to write */
	hawk_oow_t     size   /**< data size */
);

HAWK_EXPORT hawk_ooi_t hawk_pio_writebytes (
	hawk_pio_t*    pio,   /**< pio object */
	hawk_pio_hid_t hid,   /**< handle ID */
	const void*    data,  /**< data to write */
	hawk_oow_t     size   /**< data size */
);

/**
 * The hawk_pio_flush() flushes buffered data if #HAWK_PIO_TEXT has been 
 * specified to hawk_pio_open() and hawk_pio_init().
 */
HAWK_EXPORT hawk_ooi_t hawk_pio_flush (
	hawk_pio_t*    pio, /**< pio object */
	hawk_pio_hid_t hid  /**< handle ID */
);

/**
 * The hawk_pio_drain() drops unflushed input and output data in the 
 * buffer. 
 */
HAWK_EXPORT void hawk_pio_drain (
	hawk_pio_t*    pio, /**< pio object */
	hawk_pio_hid_t hid  /**< handle ID */
);

/**
 * The hawk_pio_end() function closes a pipe to a child process
 */
HAWK_EXPORT void hawk_pio_end (
	hawk_pio_t*    pio, /**< pio object */
	hawk_pio_hid_t hid  /**< handle ID */
);

/**
 * The hawk_pio_wait() function waits for a child process to terminate.
 * #HAWK_PIO_WAIT_NORETRY causes the function to return an error and set the 
 * \a pio->errnum field to #HAWK_PIO_EINTR if the underlying system call has
 * been interrupted. If #HAWK_PIO_WAIT_NOBLOCK is used, the return value of 256
 * indicates that the child process has not terminated. Otherwise, 256 is never
 * returned.
 *
 * \return
 *  -1 on error, 256 if the child is alive and #HAWK_PIO_WAIT_NOBLOCK is used,
 *  a number between 0 and 255 inclusive if the child process ends normally,
 *  256 + signal number if the child process is terminated by a signal.
 */
HAWK_EXPORT int hawk_pio_wait (
	hawk_pio_t* pio /**< pio object */
);

/**
 * The hawk_pio_kill() function terminates a child process by force.
 * You should know the danger of calling this function as the function can
 * kill a process that is not your child process if it has terminated but
 * there is a new process with the same process handle.
 * \return 0 on success, -1 on failure
 */ 
HAWK_EXPORT int hawk_pio_kill (
	hawk_pio_t* pio /**< pio object */
);

#if defined(__cplusplus)
}
#endif

#endif