gdb/target/waitstatus.h

   1 /* Target waitstatus definitions and prototypes.
   2
   3    Copyright (C) 1990-2024 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef GDB_TARGET_WAITSTATUS_H
  21 #define GDB_TARGET_WAITSTATUS_H
  22
  23 #include "diagnostics.h"
  24 #include "gdb/signals.h"
  25
  26 /* Stuff for target_wait.  */
  27
  28 /* Generally, what has the program done?  */
  29 enum target_waitkind
  30 {
  31   /* The program has exited.  The exit status is in value.integer.  */
  32   TARGET_WAITKIND_EXITED,
  33
  34   /* The program has stopped with a signal.  Which signal is in
  35      value.sig.  */
  36   TARGET_WAITKIND_STOPPED,
  37
  38   /* The program has terminated with a signal.  Which signal is in
  39      value.sig.  */
  40   TARGET_WAITKIND_SIGNALLED,
  41
  42   /* The program is letting us know that it dynamically loaded
  43      something (e.g. it called load(2) on AIX).  */
  44   TARGET_WAITKIND_LOADED,
  45
  46   /* The program has forked.  A "related" process' PTID is in
  47      value.related_pid.  I.e., if the child forks, value.related_pid
  48      is the parent's ID.  */
  49   TARGET_WAITKIND_FORKED,
  50
  51   /* The program has vforked.  A "related" process's PTID is in
  52      value.related_pid.  */
  53   TARGET_WAITKIND_VFORKED,
  54
  55   /* The program has exec'ed a new executable file.  The new file's
  56      pathname is pointed to by value.execd_pathname.  */
  57   TARGET_WAITKIND_EXECD,
  58
  59   /* The program had previously vforked, and now the child is done
  60      with the shared memory region, because it exec'ed or exited.
  61      Note that the event is reported to the vfork parent.  This is
  62      only used if GDB did not stay attached to the vfork child,
  63      otherwise, a TARGET_WAITKIND_EXECD or
  64      TARGET_WAITKIND_EXIT|SIGNALLED event associated with the child
  65      has the same effect.  */
  66   TARGET_WAITKIND_VFORK_DONE,
  67
  68   /* The program has entered or returned from a system call.  On
  69      HP-UX, this is used in the hardware watchpoint implementation.
  70      The syscall's unique integer ID number is in
  71      value.syscall_id.  */
  72   TARGET_WAITKIND_SYSCALL_ENTRY,
  73   TARGET_WAITKIND_SYSCALL_RETURN,
  74
  75   /* Nothing happened, but we stopped anyway.  This perhaps should
  76      be handled within target_wait, but I'm not sure target_wait
  77      should be resuming the inferior.  */
  78   TARGET_WAITKIND_SPURIOUS,
  79
  80   /* An event has occurred, but we should wait again.
  81      Remote_async_wait() returns this when there is an event
  82      on the inferior, but the rest of the world is not interested in
  83      it.  The inferior has not stopped, but has just sent some output
  84      to the console, for instance.  In this case, we want to go back
  85      to the event loop and wait there for another event from the
  86      inferior, rather than being stuck in the remote_async_wait()
  87      function.  This way the event loop is responsive to other events,
  88      like for instance the user typing.  */
  89   TARGET_WAITKIND_IGNORE,
  90
  91   /* The target has run out of history information,
  92      and cannot run backward any further.  */
  93   TARGET_WAITKIND_NO_HISTORY,
  94
  95   /* There are no resumed children left in the program.  */
  96   TARGET_WAITKIND_NO_RESUMED,
  97
  98   /* The thread was cloned.  The event's ptid corresponds to the
  99      cloned parent.  The cloned child is held stopped at its entry
 100      point, and its ptid is in the event's m_child_ptid.  The target
 101      must not add the cloned child to GDB's thread list until
 102      target_ops::follow_clone() is called.  */
 103   TARGET_WAITKIND_THREAD_CLONED,
 104
 105   /* The thread was created.  */
 106   TARGET_WAITKIND_THREAD_CREATED,
 107
 108   /* The thread has exited.  The exit status is in value.integer.  */
 109   TARGET_WAITKIND_THREAD_EXITED,
 110 };
 111
 112 /* Determine if KIND represents an event with a new child - a fork,
 113    vfork, or clone.  */
 114
 115 static inline bool
 116 is_new_child_status (target_waitkind kind)
 117 {
 118   return (kind == TARGET_WAITKIND_FORKED
 119           || kind == TARGET_WAITKIND_VFORKED
 120           || kind == TARGET_WAITKIND_THREAD_CLONED);
 121 }
 122
 123 /* Return KIND as a string.  */
 124
 125 static inline const char *
 126 target_waitkind_str (target_waitkind kind)
 127 {
 128 /* Make sure the compiler warns if a new TARGET_WAITKIND enumerator is added
 129    but not handled here.  */
 130 DIAGNOSTIC_PUSH
 131 DIAGNOSTIC_ERROR_SWITCH
 132   switch (kind)
 133   {
 134     case TARGET_WAITKIND_EXITED:
 135       return "EXITED";
 136     case TARGET_WAITKIND_STOPPED:
 137       return "STOPPED";
 138     case TARGET_WAITKIND_SIGNALLED:
 139       return "SIGNALLED";
 140     case TARGET_WAITKIND_LOADED:
 141       return "LOADED";
 142     case TARGET_WAITKIND_FORKED:
 143       return "FORKED";
 144     case TARGET_WAITKIND_VFORKED:
 145       return "VFORKED";
 146     case TARGET_WAITKIND_THREAD_CLONED:
 147       return "THREAD_CLONED";
 148     case TARGET_WAITKIND_EXECD:
 149       return "EXECD";
 150     case TARGET_WAITKIND_VFORK_DONE:
 151       return "VFORK_DONE";
 152     case TARGET_WAITKIND_SYSCALL_ENTRY:
 153       return "SYSCALL_ENTRY";
 154     case TARGET_WAITKIND_SYSCALL_RETURN:
 155       return "SYSCALL_RETURN";
 156     case TARGET_WAITKIND_SPURIOUS:
 157       return "SPURIOUS";
 158     case TARGET_WAITKIND_IGNORE:
 159       return "IGNORE";
 160     case TARGET_WAITKIND_NO_HISTORY:
 161       return "NO_HISTORY";
 162     case TARGET_WAITKIND_NO_RESUMED:
 163       return "NO_RESUMED";
 164     case TARGET_WAITKIND_THREAD_CREATED:
 165       return "THREAD_CREATED";
 166     case TARGET_WAITKIND_THREAD_EXITED:
 167       return "THREAD_EXITED";
 168   };
 169 DIAGNOSTIC_POP
 170
 171   gdb_assert_not_reached ("invalid target_waitkind value: %d\n", (int) kind);
 172 }
 173
 174 struct target_waitstatus
 175 {
 176   /* Default constructor.  */
 177   target_waitstatus () = default;
 178
 179   /* Copy constructor.  */
 180
 181   target_waitstatus (const target_waitstatus &other)
 182   {
 183     m_kind = other.m_kind;
 184     m_value = other.m_value;
 185
 186     if (m_kind == TARGET_WAITKIND_EXECD)
 187       m_value.execd_pathname = xstrdup (m_value.execd_pathname);
 188   }
 189
 190   /* Move constructor.  */
 191
 192   target_waitstatus (target_waitstatus &&other)
 193   {
 194     m_kind = other.m_kind;
 195     m_value = other.m_value;
 196
 197     if (m_kind == TARGET_WAITKIND_EXECD)
 198       other.m_value.execd_pathname = nullptr;
 199
 200     other.reset ();
 201   }
 202
 203   /* Copy assignment operator.  */
 204
 205   target_waitstatus &operator= (const target_waitstatus &rhs)
 206   {
 207     this->reset ();
 208     m_kind = rhs.m_kind;
 209     m_value = rhs.m_value;
 210
 211     if (m_kind == TARGET_WAITKIND_EXECD)
 212       m_value.execd_pathname = xstrdup (m_value.execd_pathname);
 213
 214     return *this;
 215   }
 216
 217   /* Move assignment operator.  */
 218
 219   target_waitstatus &operator= (target_waitstatus &&rhs)
 220   {
 221     this->reset ();
 222     m_kind = rhs.m_kind;
 223     m_value = rhs.m_value;
 224
 225     if (m_kind == TARGET_WAITKIND_EXECD)
 226       rhs.m_value.execd_pathname = nullptr;
 227
 228     rhs.reset ();
 229
 230     return *this;
 231   }
 232
 233   /* Destructor.  */
 234
 235   ~target_waitstatus ()
 236   {
 237     this->reset ();
 238   }
 239
 240   /* Setters: set the wait status kind plus any associated data.  */
 241
 242   target_waitstatus &set_exited (int exit_status)
 243   {
 244     this->reset ();
 245     m_kind = TARGET_WAITKIND_EXITED;
 246     m_value.exit_status = exit_status;
 247     return *this;
 248   }
 249
 250   target_waitstatus &set_stopped (gdb_signal sig)
 251   {
 252     this->reset ();
 253     m_kind = TARGET_WAITKIND_STOPPED;
 254     m_value.sig = sig;
 255     return *this;
 256   }
 257
 258   target_waitstatus &set_signalled (gdb_signal sig)
 259   {
 260     this->reset ();
 261     m_kind = TARGET_WAITKIND_SIGNALLED;
 262     m_value.sig = sig;
 263     return *this;
 264   }
 265
 266   target_waitstatus &set_loaded ()
 267   {
 268     this->reset ();
 269     m_kind = TARGET_WAITKIND_LOADED;
 270     return *this;
 271   }
 272
 273   target_waitstatus &set_forked (ptid_t child_ptid)
 274   {
 275     this->reset ();
 276     m_kind = TARGET_WAITKIND_FORKED;
 277     m_value.child_ptid = child_ptid;
 278     return *this;
 279   }
 280
 281   target_waitstatus &set_vforked (ptid_t child_ptid)
 282   {
 283     this->reset ();
 284     m_kind = TARGET_WAITKIND_VFORKED;
 285     m_value.child_ptid = child_ptid;
 286     return *this;
 287   }
 288
 289   target_waitstatus &set_execd (gdb::unique_xmalloc_ptr<char> execd_pathname)
 290   {
 291     this->reset ();
 292     m_kind = TARGET_WAITKIND_EXECD;
 293     m_value.execd_pathname = execd_pathname.release ();
 294     return *this;
 295   }
 296
 297   target_waitstatus &set_vfork_done ()
 298   {
 299     this->reset ();
 300     m_kind = TARGET_WAITKIND_VFORK_DONE;
 301     return *this;
 302   }
 303
 304   target_waitstatus &set_syscall_entry (int syscall_number)
 305   {
 306     this->reset ();
 307     m_kind = TARGET_WAITKIND_SYSCALL_ENTRY;
 308     m_value.syscall_number = syscall_number;
 309     return *this;
 310   }
 311
 312   target_waitstatus &set_syscall_return (int syscall_number)
 313   {
 314     this->reset ();
 315     m_kind = TARGET_WAITKIND_SYSCALL_RETURN;
 316     m_value.syscall_number = syscall_number;
 317     return *this;
 318   }
 319
 320   target_waitstatus &set_spurious ()
 321   {
 322     this->reset ();
 323     m_kind = TARGET_WAITKIND_SPURIOUS;
 324     return *this;
 325   }
 326
 327   target_waitstatus &set_ignore ()
 328   {
 329     this->reset ();
 330     m_kind = TARGET_WAITKIND_IGNORE;
 331     return *this;
 332   }
 333
 334   target_waitstatus &set_no_history ()
 335   {
 336     this->reset ();
 337     m_kind = TARGET_WAITKIND_NO_HISTORY;
 338     return *this;
 339   }
 340
 341   target_waitstatus &set_no_resumed ()
 342   {
 343     this->reset ();
 344     m_kind = TARGET_WAITKIND_NO_RESUMED;
 345     return *this;
 346   }
 347
 348   target_waitstatus &set_thread_cloned (ptid_t child_ptid)
 349   {
 350     this->reset ();
 351     m_kind = TARGET_WAITKIND_THREAD_CLONED;
 352     m_value.child_ptid = child_ptid;
 353     return *this;
 354   }
 355
 356   target_waitstatus &set_thread_created ()
 357   {
 358     this->reset ();
 359     m_kind = TARGET_WAITKIND_THREAD_CREATED;
 360     return *this;
 361   }
 362
 363   target_waitstatus &set_thread_exited (int exit_status)
 364   {
 365     this->reset ();
 366     m_kind = TARGET_WAITKIND_THREAD_EXITED;
 367     m_value.exit_status = exit_status;
 368     return *this;
 369   }
 370
 371   /* Get the kind of this wait status.  */
 372
 373   target_waitkind kind () const
 374   {
 375     return m_kind;
 376   }
 377
 378   /* Getters for the associated data.
 379
 380      Getters can only be used if the wait status is of the appropriate kind.
 381      See the setters above or the assertions below to know which data is
 382      associated to which kind.  */
 383
 384   int exit_status () const
 385   {
 386     gdb_assert (m_kind == TARGET_WAITKIND_EXITED
 387                 || m_kind == TARGET_WAITKIND_THREAD_EXITED);
 388     return m_value.exit_status;
 389   }
 390
 391   gdb_signal sig () const
 392   {
 393     gdb_assert (m_kind == TARGET_WAITKIND_STOPPED
 394                 || m_kind == TARGET_WAITKIND_SIGNALLED);
 395     return m_value.sig;
 396   }
 397
 398   ptid_t child_ptid () const
 399   {
 400     gdb_assert (is_new_child_status (m_kind));
 401     return m_value.child_ptid;
 402   }
 403
 404   const char *execd_pathname () const
 405   {
 406     gdb_assert (m_kind == TARGET_WAITKIND_EXECD);
 407     return m_value.execd_pathname;
 408   }
 409
 410   int syscall_number () const
 411   {
 412     gdb_assert (m_kind == TARGET_WAITKIND_SYSCALL_ENTRY
 413                 || m_kind == TARGET_WAITKIND_SYSCALL_RETURN);
 414     return m_value.syscall_number;
 415   }
 416
 417   /* Return a pretty printed form of target_waitstatus.
 418
 419      This is only meant to be used in debug messages, not for user-visible
 420      messages.  */
 421   std::string to_string () const;
 422
 423 private:
 424   /* Reset the wait status to its original state.  */
 425   void reset ()
 426   {
 427     if (m_kind == TARGET_WAITKIND_EXECD)
 428       xfree (m_value.execd_pathname);
 429
 430     m_kind = TARGET_WAITKIND_IGNORE;
 431   }
 432
 433   target_waitkind m_kind = TARGET_WAITKIND_IGNORE;
 434
 435   /* Additional information about the event.  */
 436   union
 437     {
 438       /* Exit status */
 439       int exit_status;
 440       /* Signal number */
 441       enum gdb_signal sig;
 442       /* Forked child pid */
 443       ptid_t child_ptid;
 444       /* execd pathname */
 445       char *execd_pathname;
 446       /* Syscall number */
 447       int syscall_number;
 448     } m_value {};
 449 };
 450
 451 /* Extended reasons that can explain why a target/thread stopped for a
 452    trap signal.  */
 453
 454 enum target_stop_reason
 455 {
 456   /* Either not stopped, or stopped for a reason that doesn't require
 457      special tracking.  */
 458   TARGET_STOPPED_BY_NO_REASON,
 459
 460   /* Stopped by a software breakpoint.  */
 461   TARGET_STOPPED_BY_SW_BREAKPOINT,
 462
 463   /* Stopped by a hardware breakpoint.  */
 464   TARGET_STOPPED_BY_HW_BREAKPOINT,
 465
 466   /* Stopped by a watchpoint.  */
 467   TARGET_STOPPED_BY_WATCHPOINT,
 468
 469   /* Stopped by a single step finishing.  */
 470   TARGET_STOPPED_BY_SINGLE_STEP
 471 };
 472
 473 #endif /* GDB_TARGET_WAITSTATUS_H */