contrib/llvm/tools/lldb/include/lldb/Host/PseudoTerminal.h

   1 //===-- PseudoTerminal.h ----------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef LLDB_HOST_PSEUDOTERMINAL_H
  11 #define LLDB_HOST_PSEUDOTERMINAL_H
  12
  13 #include <fcntl.h>
  14 #include <string>
  15
  16 #include "lldb/lldb-defines.h"
  17
  18 namespace lldb_private {
  19
  20 //----------------------------------------------------------------------
  21 /// @class PseudoTerminal PseudoTerminal.h "lldb/Host/PseudoTerminal.h"
  22 /// A pseudo terminal helper class.
  23 ///
  24 /// The pseudo terminal class abstracts the use of pseudo terminals on the
  25 /// host system.
  26 //----------------------------------------------------------------------
  27 class PseudoTerminal {
  28 public:
  29   enum {
  30     invalid_fd = -1 ///< Invalid file descriptor value
  31   };
  32
  33   //------------------------------------------------------------------
  34   /// Default constructor
  35   ///
  36   /// Constructs this object with invalid master and slave file descriptors.
  37   //------------------------------------------------------------------
  38   PseudoTerminal();
  39
  40   //------------------------------------------------------------------
  41   /// Destructor
  42   ///
  43   /// The destructor will close the master and slave file descriptors if they
  44   /// are valid and ownership has not been released using one of: @li
  45   /// PseudoTerminal::ReleaseMasterFileDescriptor() @li
  46   /// PseudoTerminal::ReleaseSaveFileDescriptor()
  47   //------------------------------------------------------------------
  48   ~PseudoTerminal();
  49
  50   //------------------------------------------------------------------
  51   /// Close the master file descriptor if it is valid.
  52   //------------------------------------------------------------------
  53   void CloseMasterFileDescriptor();
  54
  55   //------------------------------------------------------------------
  56   /// Close the slave file descriptor if it is valid.
  57   //------------------------------------------------------------------
  58   void CloseSlaveFileDescriptor();
  59
  60   //------------------------------------------------------------------
  61   /// Fork a child process that uses pseudo terminals for its stdio.
  62   ///
  63   /// In the parent process, a call to this function results in a pid being
  64   /// returned. If the pid is valid, the master file descriptor can be used
  65   /// for read/write access to stdio of the child process.
  66   ///
  67   /// In the child process the stdin/stdout/stderr will already be routed to
  68   /// the slave pseudo terminal and the master file descriptor will be closed
  69   /// as it is no longer needed by the child process.
  70   ///
  71   /// This class will close the file descriptors for the master/slave when the
  72   /// destructor is called. The file handles can be released using either: @li
  73   /// PseudoTerminal::ReleaseMasterFileDescriptor() @li
  74   /// PseudoTerminal::ReleaseSaveFileDescriptor()
  75   ///
  76   /// @param[out] error
  77   ///     An pointer to an error that can describe any errors that
  78   ///     occur. This can be NULL if no error status is desired.
  79   ///
  80   /// @return
  81   ///     @li \b Parent process: a child process ID that is greater
  82   ///         than zero, or -1 if the fork fails.
  83   ///     @li \b Child process: zero.
  84   //------------------------------------------------------------------
  85   lldb::pid_t Fork(char *error_str, size_t error_len);
  86
  87   //------------------------------------------------------------------
  88   /// The master file descriptor accessor.
  89   ///
  90   /// This object retains ownership of the master file descriptor when this
  91   /// accessor is used. Users can call the member function
  92   /// PseudoTerminal::ReleaseMasterFileDescriptor() if this object should
  93   /// release ownership of the slave file descriptor.
  94   ///
  95   /// @return
  96   ///     The master file descriptor, or PseudoTerminal::invalid_fd
  97   ///     if the master file  descriptor is not currently valid.
  98   ///
  99   /// @see PseudoTerminal::ReleaseMasterFileDescriptor()
 100   //------------------------------------------------------------------
 101   int GetMasterFileDescriptor() const;
 102
 103   //------------------------------------------------------------------
 104   /// The slave file descriptor accessor.
 105   ///
 106   /// This object retains ownership of the slave file descriptor when this
 107   /// accessor is used. Users can call the member function
 108   /// PseudoTerminal::ReleaseSlaveFileDescriptor() if this object should
 109   /// release ownership of the slave file descriptor.
 110   ///
 111   /// @return
 112   ///     The slave file descriptor, or PseudoTerminal::invalid_fd
 113   ///     if the slave file descriptor is not currently valid.
 114   ///
 115   /// @see PseudoTerminal::ReleaseSlaveFileDescriptor()
 116   //------------------------------------------------------------------
 117   int GetSlaveFileDescriptor() const;
 118
 119   //------------------------------------------------------------------
 120   /// Get the name of the slave pseudo terminal.
 121   ///
 122   /// A master pseudo terminal should already be valid prior to
 123   /// calling this function.
 124   ///
 125   /// @param[out] error
 126   ///     An pointer to an error that can describe any errors that
 127   ///     occur. This can be NULL if no error status is desired.
 128   ///
 129   /// @return
 130   ///     The name of the slave pseudo terminal as a NULL terminated
 131   ///     C. This string that comes from static memory, so a copy of
 132   ///     the string should be made as subsequent calls can change
 133   ///     this value. NULL is returned if this object doesn't have
 134   ///     a valid master pseudo terminal opened or if the call to
 135   ///     \c ptsname() fails.
 136   ///
 137   /// @see PseudoTerminal::OpenFirstAvailableMaster()
 138   //------------------------------------------------------------------
 139   const char *GetSlaveName(char *error_str, size_t error_len) const;
 140
 141   //------------------------------------------------------------------
 142   /// Open the first available pseudo terminal.
 143   ///
 144   /// Opens the first available pseudo terminal with \a oflag as the
 145   /// permissions. The opened master file descriptor is stored in this object
 146   /// and can be accessed by calling the
 147   /// PseudoTerminal::GetMasterFileDescriptor() accessor. Clients can call the
 148   /// PseudoTerminal::ReleaseMasterFileDescriptor() accessor function if they
 149   /// wish to use the master file descriptor beyond the lifespan of this
 150   /// object.
 151   ///
 152   /// If this object still has a valid master file descriptor when its
 153   /// destructor is called, it will close it.
 154   ///
 155   /// @param[in] oflag
 156   ///     Flags to use when calling \c posix_openpt(\a oflag).
 157   ///     A value of "O_RDWR|O_NOCTTY" is suggested.
 158   ///
 159   /// @param[out] error
 160   ///     An pointer to an error that can describe any errors that
 161   ///     occur. This can be NULL if no error status is desired.
 162   ///
 163   /// @return
 164   ///     @li \b true when the master files descriptor is
 165   ///         successfully opened.
 166   ///     @li \b false if anything goes wrong.
 167   ///
 168   /// @see PseudoTerminal::GetMasterFileDescriptor() @see
 169   /// PseudoTerminal::ReleaseMasterFileDescriptor()
 170   //------------------------------------------------------------------
 171   bool OpenFirstAvailableMaster(int oflag, char *error_str, size_t error_len);
 172
 173   //------------------------------------------------------------------
 174   /// Open the slave for the current master pseudo terminal.
 175   ///
 176   /// A master pseudo terminal should already be valid prior to
 177   /// calling this function. The opened slave file descriptor is stored in
 178   /// this object and can be accessed by calling the
 179   /// PseudoTerminal::GetSlaveFileDescriptor() accessor. Clients can call the
 180   /// PseudoTerminal::ReleaseSlaveFileDescriptor() accessor function if they
 181   /// wish to use the slave file descriptor beyond the lifespan of this
 182   /// object.
 183   ///
 184   /// If this object still has a valid slave file descriptor when its
 185   /// destructor is called, it will close it.
 186   ///
 187   /// @param[in] oflag
 188   ///     Flags to use when calling \c open(\a oflag).
 189   ///
 190   /// @param[out] error
 191   ///     An pointer to an error that can describe any errors that
 192   ///     occur. This can be NULL if no error status is desired.
 193   ///
 194   /// @return
 195   ///     @li \b true when the master files descriptor is
 196   ///         successfully opened.
 197   ///     @li \b false if anything goes wrong.
 198   ///
 199   /// @see PseudoTerminal::OpenFirstAvailableMaster() @see
 200   /// PseudoTerminal::GetSlaveFileDescriptor() @see
 201   /// PseudoTerminal::ReleaseSlaveFileDescriptor()
 202   //------------------------------------------------------------------
 203   bool OpenSlave(int oflag, char *error_str, size_t error_len);
 204
 205   //------------------------------------------------------------------
 206   /// Release the master file descriptor.
 207   ///
 208   /// Releases ownership of the master pseudo terminal file descriptor without
 209   /// closing it. The destructor for this class will close the master file
 210   /// descriptor if the ownership isn't released using this call and the
 211   /// master file descriptor has been opened.
 212   ///
 213   /// @return
 214   ///     The master file descriptor, or PseudoTerminal::invalid_fd
 215   ///     if the mast file descriptor is not currently valid.
 216   //------------------------------------------------------------------
 217   int ReleaseMasterFileDescriptor();
 218
 219   //------------------------------------------------------------------
 220   /// Release the slave file descriptor.
 221   ///
 222   /// Release ownership of the slave pseudo terminal file descriptor without
 223   /// closing it. The destructor for this class will close the slave file
 224   /// descriptor if the ownership isn't released using this call and the slave
 225   /// file descriptor has been opened.
 226   ///
 227   /// @return
 228   ///     The slave file descriptor, or PseudoTerminal::invalid_fd
 229   ///     if the slave file descriptor is not currently valid.
 230   //------------------------------------------------------------------
 231   int ReleaseSlaveFileDescriptor();
 232
 233 protected:
 234   //------------------------------------------------------------------
 235   // Member variables
 236   //------------------------------------------------------------------
 237   int m_master_fd; ///< The file descriptor for the master.
 238   int m_slave_fd;  ///< The file descriptor for the slave.
 239
 240 private:
 241   DISALLOW_COPY_AND_ASSIGN(PseudoTerminal);
 242 };
 243
 244 } // namespace lldb_private
 245
 246 #endif // #ifndef liblldb_PseudoTerminal_h_