| //===-- PseudoTerminal.h ----------------------------------------*- C++ -*-===// |
| // |
| // The LLVM Compiler Infrastructure |
| // |
| // This file is distributed under the University of Illinois Open Source |
| // License. See LICENSE.TXT for details. |
| // |
| //===----------------------------------------------------------------------===// |
| |
| #ifndef liblldb_PseudoTerminal_h_ |
| #define liblldb_PseudoTerminal_h_ |
| #if defined(__cplusplus) |
| |
| |
| #include <fcntl.h> |
| #include <string> |
| |
| #include "lldb/lldb-defines.h" |
| |
| namespace lldb_utility { |
| |
| //---------------------------------------------------------------------- |
| /// @class PseudoTerminal PseudoTerminal.h "lldb/Core/PseudoTerminal.h" |
| /// @brief A pseudo terminal helper class. |
| /// |
| /// The pseudo terminal class abtracts the use of pseudo terminals on |
| /// the host system. |
| //---------------------------------------------------------------------- |
| class PseudoTerminal |
| { |
| public: |
| enum |
| { |
| invalid_fd = -1 ///< Invalid file descriptor value |
| }; |
| |
| //------------------------------------------------------------------ |
| /// Default constructor |
| /// |
| /// Constructs this object with invalid master and slave file |
| /// descriptors. |
| //------------------------------------------------------------------ |
| PseudoTerminal (); |
| |
| //------------------------------------------------------------------ |
| /// Destructor |
| /// |
| /// The destructor will close the master and slave file descriptors |
| /// if they are valid and ownwership has not been released using |
| /// one of: |
| /// @li PseudoTerminal::ReleaseMasterFileDescriptor() |
| /// @li PseudoTerminal::ReleaseSaveFileDescriptor() |
| //------------------------------------------------------------------ |
| ~PseudoTerminal (); |
| |
| //------------------------------------------------------------------ |
| /// Close the master file descriptor if it is valid. |
| //------------------------------------------------------------------ |
| void |
| CloseMasterFileDescriptor (); |
| |
| //------------------------------------------------------------------ |
| /// Close the slave file descriptor if it is valid. |
| //------------------------------------------------------------------ |
| void |
| CloseSlaveFileDescriptor (); |
| |
| //------------------------------------------------------------------ |
| /// Fork a child process that uses pseudo terminals for its stdio. |
| /// |
| /// In the parent process, a call to this function results in a pid |
| /// being returned. If the pid is valid, the master file descriptor |
| /// can be used for read/write access to stdio of the child process. |
| /// |
| /// In the child process the stdin/stdout/stderr will already be |
| /// routed to the slave pseudo terminal and the master file |
| /// descriptor will be closed as it is no longer needed by the child |
| /// process. |
| /// |
| /// This class will close the file descriptors for the master/slave |
| /// when the destructor is called. The file handles can be released |
| /// using either: |
| /// @li PseudoTerminal::ReleaseMasterFileDescriptor() |
| /// @li PseudoTerminal::ReleaseSaveFileDescriptor() |
| /// |
| /// @param[out] error |
| /// An pointer to an error that can describe any errors that |
| /// occur. This can be NULL if no error status is desired. |
| /// |
| /// @return |
| /// @li \b Parent process: a child process ID that is greater |
| /// than zero, or -1 if the fork fails. |
| /// @li \b Child process: zero. |
| //------------------------------------------------------------------ |
| lldb::pid_t |
| Fork (char *error_str, size_t error_len); |
| |
| //------------------------------------------------------------------ |
| /// The master file descriptor accessor. |
| /// |
| /// This object retains ownership of the master file descriptor when |
| /// this accessor is used. Users can call the member function |
| /// PseudoTerminal::ReleaseMasterFileDescriptor() if this |
| /// object should release ownership of the slave file descriptor. |
| /// |
| /// @return |
| /// The master file descriptor, or PseudoTerminal::invalid_fd |
| /// if the master file descriptor is not currently valid. |
| /// |
| /// @see PseudoTerminal::ReleaseMasterFileDescriptor() |
| //------------------------------------------------------------------ |
| int |
| GetMasterFileDescriptor () const; |
| |
| //------------------------------------------------------------------ |
| /// The slave file descriptor accessor. |
| /// |
| /// This object retains ownership of the slave file descriptor when |
| /// this accessor is used. Users can call the member function |
| /// PseudoTerminal::ReleaseSlaveFileDescriptor() if this |
| /// object should release ownership of the slave file descriptor. |
| /// |
| /// @return |
| /// The slave file descriptor, or PseudoTerminal::invalid_fd |
| /// if the slave file descriptor is not currently valid. |
| /// |
| /// @see PseudoTerminal::ReleaseSlaveFileDescriptor() |
| //------------------------------------------------------------------ |
| int |
| GetSlaveFileDescriptor () const; |
| |
| //------------------------------------------------------------------ |
| /// Get the name of the slave pseudo terminal. |
| /// |
| /// A master pseudo terminal should already be valid prior to |
| /// calling this function. |
| /// |
| /// @param[out] error |
| /// An pointer to an error that can describe any errors that |
| /// occur. This can be NULL if no error status is desired. |
| /// |
| /// @return |
| /// The name of the slave pseudo terminal as a NULL terminated |
| /// C. This string that comes from static memory, so a copy of |
| /// the string should be made as subsequent calls can change |
| /// this value. NULL is returned if this object doesn't have |
| /// a valid master pseudo terminal opened or if the call to |
| /// \c ptsname() fails. |
| /// |
| /// @see PseudoTerminal::OpenFirstAvailableMaster() |
| //------------------------------------------------------------------ |
| const char* |
| GetSlaveName (char *error_str, size_t error_len) const; |
| |
| //------------------------------------------------------------------ |
| /// Open the first available pseudo terminal. |
| /// |
| /// Opens the first available pseudo terminal with \a oflag as the |
| /// permissions. The opened master file descriptor is stored in this |
| /// object and can be accessed by calling the |
| /// PseudoTerminal::GetMasterFileDescriptor() accessor. Clients |
| /// can call the PseudoTerminal::ReleaseMasterFileDescriptor() |
| /// accessor function if they wish to use the master file descriptor |
| /// beyond the lifespan of this object. |
| /// |
| /// If this object still has a valid master file descriptor when its |
| /// destructor is called, it will close it. |
| /// |
| /// @param[in] oflag |
| /// Flags to use when calling \c posix_openpt(\a oflag). |
| /// A value of "O_RDWR|O_NOCTTY" is suggested. |
| /// |
| /// @param[out] error |
| /// An pointer to an error that can describe any errors that |
| /// occur. This can be NULL if no error status is desired. |
| /// |
| /// @return |
| /// @li \b true when the a master files descriptor is |
| /// successfully opened. |
| /// @li \b false if anything goes wrong. |
| /// |
| /// @see PseudoTerminal::GetMasterFileDescriptor() |
| /// @see PseudoTerminal::ReleaseMasterFileDescriptor() |
| //------------------------------------------------------------------ |
| bool |
| OpenFirstAvailableMaster (int oflag, char *error_str, size_t error_len); |
| |
| //------------------------------------------------------------------ |
| /// Open the slave for the current master pseudo terminal. |
| /// |
| /// A master pseudo terminal should already be valid prior to |
| /// calling this function. The opened slave file descriptor is |
| /// stored in this object and can be accessed by calling the |
| /// PseudoTerminal::GetSlaveFileDescriptor() accessor. Clients |
| /// can call the PseudoTerminal::ReleaseSlaveFileDescriptor() |
| /// accessor function if they wish to use the slave file descriptor |
| /// beyond the lifespan of this object. |
| /// |
| /// If this object still has a valid slave file descriptor when its |
| /// destructor is called, it will close it. |
| /// |
| /// @param[in] oflag |
| /// Flags to use when calling \c open(\a oflag). |
| /// |
| /// @param[out] error |
| /// An pointer to an error that can describe any errors that |
| /// occur. This can be NULL if no error status is desired. |
| /// |
| /// @return |
| /// @li \b true when the a master files descriptor is |
| /// successfully opened. |
| /// @li \b false if anything goes wrong. |
| /// |
| /// @see PseudoTerminal::OpenFirstAvailableMaster() |
| /// @see PseudoTerminal::GetSlaveFileDescriptor() |
| /// @see PseudoTerminal::ReleaseSlaveFileDescriptor() |
| //------------------------------------------------------------------ |
| bool |
| OpenSlave (int oflag, char *error_str, size_t error_len); |
| |
| //------------------------------------------------------------------ |
| /// Release the master file descriptor. |
| /// |
| /// Releases ownership of the master pseudo terminal file descriptor |
| /// without closing it. The destructor for this class will close the |
| /// master file descriptor if the ownership isn't released using this |
| /// call and the master file descriptor has been opened. |
| /// |
| /// @return |
| /// The master file descriptor, or PseudoTerminal::invalid_fd |
| /// if the mast file descriptor is not currently valid. |
| //------------------------------------------------------------------ |
| int |
| ReleaseMasterFileDescriptor (); |
| |
| //------------------------------------------------------------------ |
| /// Release the slave file descriptor. |
| /// |
| /// Release ownership of the slave pseudo terminal file descriptor |
| /// without closing it. The destructor for this class will close the |
| /// slave file descriptor if the ownership isn't released using this |
| /// call and the slave file descriptor has been opened. |
| /// |
| /// @return |
| /// The slave file descriptor, or PseudoTerminal::invalid_fd |
| /// if the slave file descriptor is not currently valid. |
| //------------------------------------------------------------------ |
| int |
| ReleaseSlaveFileDescriptor (); |
| |
| protected: |
| //------------------------------------------------------------------ |
| // Member variables |
| //------------------------------------------------------------------ |
| int m_master_fd; ///< The file descriptor for the master. |
| int m_slave_fd; ///< The file descriptor for the slave. |
| |
| private: |
| DISALLOW_COPY_AND_ASSIGN (PseudoTerminal); |
| |
| }; |
| |
| } // namespace lldb |
| |
| #endif // #if defined(__cplusplus) |
| #endif // #ifndef liblldb_PseudoTerminal_h_ |
