Exec.hpp

Go to the documentation of this file.

/*******************************************************************************
* Copyright (C) 2005, Quest Software, Inc. All rights reserved.
* Copyright (C) 2006, Novell, Inc. All rights reserved.
* 
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
* 
*     * Redistributions of source code must retain the above copyright notice,
*       this list of conditions and the following disclaimer.
*     * 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.
*     * Neither the name of 
*       Quest Software, Inc., 
*       nor Novell, Inc., 
*       nor the names of its contributors or employees may be used to 
*       endorse or promote products derived from this software without 
*       specific prior written permission.
* 
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "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 COPYRIGHT OWNER OR CONTRIBUTORS 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 BLOCXX_EXEC_HPP_INCLUDE_GUARD_
#define BLOCXX_EXEC_HPP_INCLUDE_GUARD_

#include "blocxx/BLOCXX_config.h"
#include "blocxx/CommonFwd.hpp"
#include "blocxx/EnvVars.hpp"
#include "blocxx/Process.hpp"
#ifdef BLOCXX_ENABLE_TEST_HOOKS
#include "blocxx/GlobalPtr.hpp"
#endif

namespace BLOCXX_NAMESPACE
{

BLOCXX_DECLARE_APIEXCEPTION(ExecError, BLOCXX_COMMON_API);
BLOCXX_DECLARE_APIEXCEPTION2(ExecTimeout, ExecErrorException, BLOCXX_COMMON_API);
BLOCXX_DECLARE_APIEXCEPTION2(ExecBufferFull, ExecErrorException, BLOCXX_COMMON_API);

namespace Exec
{
   BLOCXX_COMMON_API Process::Status system(const Array<String>& command,
      const char* const envp[] = 0, const Timeout& = Timeout::infinite);

   template <typename SA1, typename SA2>
   Process::Status system(const SA1& command,
      const SA2& envVars, const Timeout& timeout = Timeout::infinite)
   {
      Cstr::CstrArr<SA1> sa_command(command);
      Cstr::CstrArr<SA2> sa_envVars(envVars);
      return system(sa_command.sarr, sa_envVars.sarr, timeout);
   }

   BLOCXX_COMMON_API int safeSystem(const Array<String>& command,
      const char* const envp[] = 0) BLOCXX_DEPRECATED;


   class BLOCXX_COMMON_API PreExec
   {
   public:
      typedef ::BLOCXX_NAMESPACE::UnnamedPipe* pipe_pointer_t;

      PreExec(bool precompute_max_descriptors = false);

      virtual ~PreExec();

      virtual bool keepStd(int d) const = 0;

      struct Error
      {
         enum { MAX_MSG_LEN = 64 };
         char message[MAX_MSG_LEN + 1]; // must be null-terminated
         int error_num;        // errno value; 0 means no errno value
      };

      struct DontCatch
      {
         virtual ~DontCatch();
      };

      virtual void call(pipe_pointer_t const pparr[]) = 0;

      void closeDescriptorsOnExec(std::vector<bool> const & keep);

      static void resetSignals();

      static void closePipesOnExec(pipe_pointer_t const pparr[]);

      static void setupStandardDescriptors(pipe_pointer_t const pparr[]);

      static void setNewProcessGroup();

   protected:
      long m_max_descriptors;
   };

   static char const * const * const currentEnvironment = 0;

   BLOCXX_COMMON_API ProcessRef spawn(
      char const * exec_path,
      char const * const argv[], char const * const envp[],
      PreExec & pre_exec
   );

   template <typename S, typename SA1, typename SA2>
   ProcessRef spawn(
      S const & exec_path, SA1 const & argv, SA2 const & envp,
      PreExec & pre_exec
   )
   {
      Cstr::CstrArr<SA1> sa_argv(argv);
      Cstr::CstrArr<SA2> sa_envp(envp);
      char const * s_exec_path = Cstr::to_char_ptr(exec_path);
      return spawn(s_exec_path, sa_argv.sarr, sa_envp.sarr, pre_exec);
   }

   //
   BLOCXX_COMMON_API ProcessRef spawn(
      char const * const argv[], char const * const envp[]
   );

   template <typename SA1, typename SA2>
   ProcessRef spawn(
      SA1 const & argv, SA2 const & envp
   )
   {
      Cstr::CstrArr<SA1> sa_argv(argv);
      Cstr::CstrArr<SA2> sa_envp(envp);
      return spawn(sa_argv.sarr, sa_envp.sarr);
   }

   template <typename SA1>
   ProcessRef spawn(
      SA1 const & argv
   )
   {
      return spawn(argv, Exec::currentEnvironment);
   }

   BLOCXX_COMMON_API void gatherOutput(String& output, const ProcessRef& proc, const Timeout& timeout = Timeout::infinite, int outputlimit = -1);
   
   enum EOutputSource
   {
      E_STDOUT,
      E_STDERR
   };

   class BLOCXX_COMMON_API OutputCallback
   {
   public:
      virtual ~OutputCallback();
      void handleData(const char* data, size_t dataLen, EOutputSource outputSource, const ProcessRef& theProc, size_t streamIndex, Array<char>& inputBuffer);
   private:
      virtual void doHandleData(const char* data, size_t dataLen, EOutputSource outputSource, const ProcessRef& theProc, size_t streamIndex, Array<char>& inputBuffer) = 0;
   };

   class BLOCXX_COMMON_API InputCallback
   {
   public:
      virtual ~InputCallback();
      void getData(Array<char>& inputBuffer, const ProcessRef& theProc, size_t streamIndex);
   private:
      virtual void doGetData(Array<char>& inputBuffer, const ProcessRef& theProc, size_t streamIndex) = 0;
   };
#if 0
   enum EProcessRunning
   {
      E_PROCESS_RUNNING,
      E_PROCESS_EXITED
   };

   // class invariant: if m_running == E_PROCESS_RUNNING, then m_status == 0.
   class ProcessStatus
   {
   public:
      ProcessStatus()
      : m_running(E_PROCESS_RUNNING)
      , m_status(0)
      {
      }

      explicit ProcessStatus(int status)
      : m_running(E_PROCESS_EXITED)
      , m_status(status)
      {
      }

      bool hasExited() const
      {
         return m_running == E_PROCESS_EXITED;
      }

      const int& getStatus() const
      {
         return m_status;
      }
   private:
      EProcessRunning m_running;
      int m_status;
   };
#endif

   BLOCXX_COMMON_API void processInputOutput(OutputCallback& output, Array<ProcessRef>& procs,
      InputCallback& input, const Timeout& timeout = Timeout::infinite);
   

   BLOCXX_COMMON_API void processInputOutput(const String& input, String& output, const ProcessRef& process, 
      const Timeout& timeout = Timeout::infinite, int outputlimit = -1);

   BLOCXX_COMMON_API Process::Status feedProcessAndGatherOutput(
      ProcessRef const & proc, String & output,
      Timeout const & timeout = Timeout::infinite, int outputlimit = -1,
      String const & input = String());

   BLOCXX_COMMON_API Process::Status feedProcessAndGatherOutput(
      ProcessRef const & proc, String & output,
      String & erroutput, Timeout const & timeout = Timeout::infinite,
      int outputLimit = -1, 
      String const & input = String());

   BLOCXX_COMMON_API Process::Status executeProcessAndGatherOutput(
      char const * const command[], String& output, char const * const envVars[],
      const Timeout& timeout = Timeout::infinite, int outputlimit = -1,
      char const * input = 0);

   BLOCXX_COMMON_API Process::Status executeProcessAndGatherOutput(
      char const * const command[], String& output, String& erroutput,
      char const * const envVars[],
      const Timeout& timeout = Timeout::infinite, int outputLimit = -1,
      char const * input = 0);
   
   template <typename SA1, typename S1, typename S2>
   Process::Status executeProcessAndGatherOutput(
      SA1 const & command, S1& output,
      const Timeout& timeout, int outputlimit, S2 const& input)
   {
      Cstr::CstrArr<SA1> sa_command(command);
      String tmpOutput;
      char const * sInput = Cstr::to_char_ptr(input);
      Process::Status res;
      try
      {
         res = executeProcessAndGatherOutput(sa_command.sarr, tmpOutput,
            currentEnvironment,  timeout, outputlimit, sInput);
      }
      catch(...)
      {
         output = tmpOutput.c_str();
         throw;
      }
      output = tmpOutput.c_str();
      return res;
   }

   template <typename SA1, typename S1, typename S2>
   Process::Status executeProcessAndGatherOutput(
      SA1 const & command, S1& output, S1& erroutput,
      const Timeout& timeout, int outputlimit, S2 const& input)
   {
      Cstr::CstrArr<SA1> sa_command(command);
      String tmpOutput, tmpErrOut;
      char const * sInput = Cstr::to_char_ptr(input);
      Process::Status res;
      try
      {
         res = executeProcessAndGatherOutput(sa_command.sarr, tmpOutput,
            tmpErrOut, currentEnvironment,   timeout, outputlimit, sInput);
      }
      catch(...)
      {
         output = tmpOutput.c_str();
         erroutput = tmpErrOut.c_str();
         throw;
      }
      output = tmpOutput.c_str();
      erroutput = tmpErrOut.c_str();
      return res;
   }

   template <typename SA1, typename S1>
   Process::Status executeProcessAndGatherOutput(
      SA1 const & command, S1& output,
      const Timeout& timeout = Timeout::infinite, int outputlimit = -1)
   {
      Cstr::CstrArr<SA1> sa_command(command);
      String tmpOutput;
      Process::Status res;
      try
      {
         res = executeProcessAndGatherOutput(sa_command.sarr, tmpOutput,
            currentEnvironment,  timeout, outputlimit, (char const*)0);
      }
      catch(...)
      {
         output = tmpOutput.c_str();
         throw;
      }
      output = tmpOutput.c_str();
      return res;
   }

   template <typename SA1, typename S1>
   Process::Status executeProcessAndGatherOutput(
      SA1 const & command, S1& output, S1& erroutput,
      const Timeout& timeout = Timeout::infinite, int outputlimit = -1)
   {
      Cstr::CstrArr<SA1> sa_command(command);
      String tmpOutput, tmpErrOut;
      Process::Status res;
      try
      {
         res = executeProcessAndGatherOutput(sa_command.sarr, tmpOutput,
            tmpErrOut, currentEnvironment,   timeout, outputlimit,
            (char const*)0);
      }
      catch(...)
      {
         output = tmpOutput.c_str();
         erroutput = tmpErrOut.c_str();
         throw;
      }
      output = tmpOutput.c_str();
      erroutput = tmpErrOut.c_str();
      return res;
   }

   template <typename SA1, typename S1, typename SA2, typename S2>
   Process::Status executeProcessAndGatherOutput(
      SA1 const & command, S1& output, SA2 const & envp,
      const Timeout& timeout, int outputlimit, S2 const& input)
   {
      Cstr::CstrArr<SA1> sa_command(command);
      Cstr::CstrArr<SA2> sa_envp(envp);
      String tmpOutput;
      char const * sInput = Cstr::to_char_ptr(input);
      Process::Status res;
      try
      {
         res = executeProcessAndGatherOutput(sa_command.sarr, tmpOutput, sa_envp.sarr,
            timeout, outputlimit, sInput);
      }
      catch(...)
      {
         output = tmpOutput.c_str();
         throw;
      }
      output = tmpOutput.c_str();
      return res;
   }

   template <typename SA1, typename S1, typename SA2, typename S2>
   Process::Status executeProcessAndGatherOutput(
      SA1 const & command, S1& output, S1& erroutput, SA2 const & envp,
      const Timeout& timeout, int outputlimit, S2 const& input)
   {
      Cstr::CstrArr<SA1> sa_command(command);
      Cstr::CstrArr<SA2> sa_envp(envp);
      String tmpOutput, tmpErrOut;
      char const * sInput = Cstr::to_char_ptr(input);
      Process::Status res;
      try
      {
         res = executeProcessAndGatherOutput(sa_command.sarr, tmpOutput,
            tmpErrOut, sa_envp.sarr, timeout, outputlimit, sInput);
      }
      catch(...)
      {
         output = tmpOutput.c_str();
         erroutput = tmpErrOut.c_str();
         throw;
      }
      output = tmpOutput.c_str();
      erroutput = tmpErrOut.c_str();
      return res;
   }

   template <typename SA1, typename S1, typename SA2>
   Process::Status executeProcessAndGatherOutput(
      SA1 const & command, S1& output, S1& erroutput, SA2 const & envp,
      const Timeout& timeout = Timeout::infinite, int outputlimit = -1)
   {
      return executeProcessAndGatherOutput(command, output, erroutput, envp,
         timeout, outputlimit, String());
   }


   BLOCXX_COMMON_API void executeProcessAndGatherOutput(
      const Array<String>& command,
      String& output, int& processstatus,
      int timeoutsecs = -1, int outputlimit = -1, 
      const String& input = String()) BLOCXX_DEPRECATED;
   
   namespace Impl
   {
      // internal implementation details, not meant for use outside of *Exec.?pp files.
      unsigned const BLOCXX_IN      = 0;
      unsigned const BLOCXX_OUT     = 1;
      unsigned const BLOCXX_SERR    = 2;
      unsigned const BLOCXX_EXEC_ERR   = 3;
      unsigned const BLOCXX_NPIPE      = 4;
      void close_child_ends(UnnamedPipeRef ppipe[BLOCXX_NPIPE]);

      struct NullFactory
      {
         static void* create()
         {
            return 0;
         }
      };
   } // end namespace Impl

#ifdef BLOCXX_ENABLE_TEST_HOOKS
   typedef GlobalPtr<ExecMockObject, Impl::NullFactory> ExecMockObject_t;
   extern ExecMockObject_t g_execMockObject;
#endif
} // end namespace Exec

} // end namespace BLOCXX_NAMESPACE

#endif