ROSE  0.11.109.0
Linux.h
1 #ifndef ROSE_BinaryAnalysis_Debugger_Linux_H
2 #define ROSE_BinaryAnalysis_Debugger_Linux_H
3 #include <featureTests.h>
4 #ifdef ROSE_ENABLE_DEBUGGER_LINUX
5 
6 #include <Rose/BinaryAnalysis/Debugger/Base.h>
7 
8 #include <Sawyer/Optional.h>
9 
10 namespace Rose {
11 namespace BinaryAnalysis {
12 namespace Debugger {
13 
15 class Linux: public Base {
17  // Types
19 public:
21  using Ptr = LinuxPtr;
22 
24  enum class DetachMode {
25  KILL,
26  DETACH,
27  CONTINUE,
28  NOTHING
29  };
30 
32  enum class Flag {
33  ATTACH = 0x00000001,
34  REDIRECT_INPUT = 0x00000002,
35  REDIRECT_OUTPUT = 0x00000004,
36  REDIRECT_ERROR = 0x00000008,
37  CLOSE_FILES = 0x00000010,
38  DEFAULT_FLAGS = 0x00000013
39  };
40 
44  class Specimen {
45  BitFlags<Flag> flags_; // operational flags
46  unsigned long persona_; // personality(2) flags
47 
48  // Members for running a program
49  boost::filesystem::path program_; // full path of executable program
50  std::vector<std::string> arguments_; // command-line arguments of executable program
51  boost::filesystem::path workingDirectory_; // name or working directory, or use CWD if empty
52  std::vector<boost::regex> clearEnvVars_; // clear environment variables matching these patterns
53  std::map<std::string, std::string> setEnvVars_; // environment variables to be set
54 
55  // Members for attaching to a process
56  int pid_ = -1; // process ID (int instead of pid_t for portability)
57 
58  public:
60  Specimen();
61 
63  Specimen(int pid); // implicit
64 
66  Specimen(const boost::filesystem::path&); // implicit
67 
69  Specimen(const boost::filesystem::path &name, const std::vector<std::string> &args);
70 
72  Specimen(const std::vector<std::string> &nameAndArgs); // implicit
73 
74  public:
81  const boost::filesystem::path& program() const;
82  void program(const boost::filesystem::path&);
91  const std::vector<std::string>& arguments() const;
92  void arguments(const std::vector<std::string>&);
100  void eraseEnvironmentVariable(const std::string&);
101 
107  void eraseMatchingEnvironmentVariables(const boost::regex&);
108 
112  void eraseAllEnvironmentVariables();
113 
119  void insertEnvironmentVariable(const std::string &name, const std::string &value);
120 
128  boost::filesystem::path workingDirectory() const;
129  void workingDirectory(const boost::filesystem::path&);
137  const BitFlags<Flag>& flags() const;
138  BitFlags<Flag>& flags();
148  unsigned long persona() const;
149  void persona(unsigned long bits);
160  bool randomizedAddresses() const;
161  void randomizedAddresses(bool);
170  int process() const;
171  void process(int pid);
175  void print(std::ostream &out) const;
176 
177  // Used internally.
178  char** prepareEnvAdjustments() const;
179  };
180 
182  using RegisterPage = std::array<uint8_t, 512>;
183 
185  struct AllRegisters {
186  RegisterPage regs;
187  RegisterPage fpregs;
188  };
189 
191  // Data members
193 private:
195  enum class RegPage { NONE, REGS, FPREGS };
196 
197  Specimen specimen_; // description of specimen being debugged
198  int child_ = 0; // process being debugged (int, not pid_t, for Windows portability)
199  DetachMode autoDetach_ = DetachMode::KILL; // how to detach from the subordinate when deleting this debugger
200  int wstat_ = -1; // last status from waitpid
201  AddressIntervalSet breakPoints_; // list of break point addresses
202  int sendSignal_ = 0; // pending signal
203  UserRegDefs userRegDefs_; // how registers map to user_regs_struct in <sys/user.h>
204  UserRegDefs userFpRegDefs_; // how registers map to user_fpregs_struct in <sys/user.h>
205  size_t kernelWordSize_ = 0; // cached width in bits of kernel's words
206  RegisterPage regsPage_; // latest register information read from subordinate
207  RegPage regsPageStatus_ = RegPage::NONE; // what are the contents of regsPage_?
208  Sawyer::Optional<rose_addr_t> syscallVa_; // address of some executable system call instruction.
209 
211  // Initialization and destruction.
213 public:
217  static Ptr instance();
218 
220  static Ptr instance(const Specimen &specimen, Sawyer::Optional<DetachMode> onDelete = Sawyer::Nothing());
221 
222  Linux();
223  ~Linux();
224 
226  // Attaching and detaching
228 public:
236  void attach(const Specimen&, Sawyer::Optional<DetachMode> onDelete = Sawyer::Nothing());
240  Sawyer::Optional<int> processId() const;
241 
247  DetachMode detachMode() const;
248  void detachMode(DetachMode);
254  size_t kernelWordSize();
255 
257  int waitpidStatus() const;
258 
260  // Running
262 public:
264  void stepIntoSystemCall(ThreadId);
265 
270  void runToSystemCall(ThreadId);
271 
273  // Register operations
275 public:
279  virtual AllRegisters readAllRegisters(ThreadId);
280 
284  virtual void writeAllRegisters(ThreadId, const AllRegisters&);
285 
287  // System calls
289 public:
293  int64_t remoteSystemCall(ThreadId, int syscallNumber);
294  int64_t remoteSystemCall(ThreadId, int syscallNumber,
295  uint64_t arg1);
296  int64_t remoteSystemCall(ThreadId, int syscallNumber,
297  uint64_t arg1, uint64_t arg2);
298  int64_t remoteSystemCall(ThreadId, int syscallNumber,
299  uint64_t arg1, uint64_t arg2, uint64_t arg3);
300  int64_t remoteSystemCall(ThreadId, int syscallNumber,
301  uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4);
302  int64_t remoteSystemCall(ThreadId, int syscallNumber,
303  uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5);
304  int64_t remoteSystemCall(ThreadId, int syscallNumber,
305  uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5, uint64_t arg6);
306  int64_t remoteSystemCall(ThreadId, int syscallNumber, std::vector<uint64_t> args);
313  int remoteOpenFile(ThreadId, const boost::filesystem::path &fileName, unsigned flags, mode_t mode);
314 
316  int remoteCloseFile(ThreadId, unsigned remoteFd);
317 
321  rose_addr_t remoteMmap(ThreadId, rose_addr_t va, size_t nBytes, unsigned prot, unsigned flags, const boost::filesystem::path&,
322  off_t offset);
323 
325  // Overrides for methods declared and documented in the super class.
327 public:
328  virtual bool isAttached() override;
329  virtual void detach() override;
330  virtual void terminate() override;
331  virtual std::vector<ThreadId> threadIds() override;
332  virtual void executionAddress(ThreadId, rose_addr_t) override;
333  virtual rose_addr_t executionAddress(ThreadId) override;
334  virtual void setBreakPoint(const AddressInterval&) override;
335  virtual void clearBreakPoint(const AddressInterval&) override;
336  virtual void clearBreakPoints() override;
337  virtual void singleStep(ThreadId) override;
338  virtual void runToBreakPoint(ThreadId) override;
339  virtual Sawyer::Container::BitVector readRegister(ThreadId, RegisterDescriptor) override;
340  virtual void writeRegister(ThreadId, RegisterDescriptor, const Sawyer::Container::BitVector&) override;
341  virtual void writeRegister(ThreadId, RegisterDescriptor, uint64_t value) override;
342  virtual size_t readMemory(rose_addr_t va, size_t nBytes, uint8_t *buffer) override;
343  virtual std::vector<uint8_t> readMemory(rose_addr_t va, size_t nBytes) override;
344  virtual Sawyer::Container::BitVector readMemory(rose_addr_t va, size_t nBytes, ByteOrder::Endianness order) override;
345  virtual size_t writeMemory(rose_addr_t va, size_t nBytes, const uint8_t *bytes) override;
346  virtual bool isTerminated() override;
347  virtual std::string howTerminated() override;
348 
349 private:
350  // Wait for subordinate or throw on error
351  void waitForChild();
352 
353  // Open /dev/null with the specified flags as the indicated file descriptor, closing what was previously on that
354  // descriptor. If an error occurs, the targetFd is closed anyway.
355  void devNullTo(int targetFd, int openFlags);
356 
357  // Get/set personality in a portable way
358  static unsigned long getPersonality();
359  static void setPersonality(unsigned long);
360 
361  // Address of a system call instruction. The initial search can be expensive, so the result is cached.
362  Sawyer::Optional<rose_addr_t> findSystemCall();
363 };
364 
365 std::ostream& operator<<(std::ostream&, const Linux::Specimen&);
366 
367 } // namespace
368 } // namespace
369 } // namespace
370 
371 #endif
372 #endif
const char * DetachMode(int64_t)
Convert Rose::BinaryAnalysis::Debugger::Linux::DetachMode enum constant to a string.
void print(const StackVariables &, const Partitioner2::Partitioner &, std::ostream &out, const std::string &prefix="")
Print info about multiple local variables.
Main namespace for the ROSE library.
const char * RegPage(int64_t)
Convert Rose::BinaryAnalysis::Debugger::Linux::RegPage enum constant to a string. ...
Sawyer::SharedPointer< Node > Ptr
Reference counting pointer.
Represents no value.
Definition: Optional.h:32
Container associating values with keys.
Definition: Sawyer/Map.h:66