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