Provided by: manpages-de-dev_0.10-1_all bug

BEZEICHNUNG

       ptrace - Prozessverfolgung

"UBERSICHT

       #include <sys/ptrace.h>

       long ptrace(enum __ptrace_request abfrage, pid_t pid,
                   void *adresse, void *daten);

BESCHREIBUNG

       Der  Systemaufruf  ptrace()  stellt  ein  Mittel  bereit,  wodurch  ein
       Elternprozess die Ausfuhrung eines  anderen  Prozesses  beobachten  und
       steuern  kann und sein Kernel-Abbild sowie die Register untersuchen und
       andern kann. Er wird in erster Linie benutzt,  um  Fehlersuche  mittels
       Haltepunkten zu implementieren und Systemaufrufe zu verfolgen.

       Der  Elternprozess kann eine Verfolgung mittels fork(2) starten und als
       Ergebnis einen Kindprozess erhalten, der PTRACE_TRACEME  ausfuhrt,  was
       (ublicherweise)  von  einem  exec(3)  gefolgt wird. Alternativ kann der
       Elternprozess die  Verfolgung  eines  existierenden  Prozesses  mittels
       PTRACE_ATTACH beginnen.

       Wahrend  der  Kindprozess verfolgt wird, wird er jedesmal stoppen, wenn
       ein Signal gesandt wird, sogar wenn das Signal  ignoriert  wird.  (Eine
       Ausnahme   ist   SIGKILL,  das  seine  normale  Wirkung  erzielt.)  Der
       Elternprozess wird  bei  seinem  nachsten  wait(2)  benachrichtigt  und
       konnte  den  Kindprozess prufen und verandern, wahrend er gestoppt ist.
       Der Elternprozess veranlasst den Kindprozess anschlieBend  fortzufahren
       und  wahlweise  das  versandte  Signal  zu ignorieren (oder stattdessen
       sogar ein anderes Signal zu senden).

       Wenn der  Elternprozess  die  Verfolgung  beendet  hat,  kann  der  den
       Kindprozess   mit   PTRACE_KILL  beenden  oder  ihn  mit  PTRACE_DETACH
       veranlassen in einem normalen, nicht verfolgten Modus fortzufahren.

       Der Wert des Arguments abfrage legt die Aktion des Systemaufrufs fest:

       PTRACE_TRACEME
              zeigt an, dass der Prozess  von  seinem  Elternprozess  verfolgt
              wird.  Jedes  Signal  (auBer  SIGKILL),  das  an  diesen Prozess
              gesandt wird, wird ihn stoppen und seinen Elternprozess  mittels
              wait(2)   benachrichtigen.  AuBerdem  werden  alle  nachrangigen
              Aufrufe von execve(2) durch diesen Prozess  bewirken,  dass  ihm
              ein  SIGTRAP  gesandt wird, das es dem Elternprozess ermoglicht,
              die Kontrolle daruber  zu  erlangen,  bevor  das  neue  Programm
              ausgefuhrt wird. Ein Prozess sollte diese Anfrage wahrscheinlich
              nicht senden, wenn sein  Elternprozess  nicht  erwartet  ihn  zu
              verfolgen. (pid, adresse und daten werden ignoriert.)

       Die vorhergehende Anfrage wird nur vom Kindprozess benutzt; die ubrigen
       werden nur vom Elternprozess benutzt. In den  folgenden  Anfragen  gibt
       pid  den  Kindprozess  an,  auf  den eingewirkt werden soll. Fur andere
       Anfragen als PTRACE_KILL muss der Kindprozess gestoppt werden.

       PTRACE_PEEKTEXT, PTRACE_PEEKDATA
              Liest ein  >>word<<  an  der  Stelle  adresse  im  Speicher  des
              Kindprozesses   und   gibt   das   >>word<<   als  Ergebnis  des
              ptrace()-Aufrufs zuruck. Linux hat keine  separaten  Adressraume
              fur  Text  und  Daten,  daher  sind  die beiden Abfragen derzeit
              gleichwertig. (Das Argument daten wird ignoriert.)

       PTRACE_PEEKUSER
              Liest ein >>word<< bei Versatz adresse  im  BENUTZERbereich  des
              Kindprozesses,  der  die  Register und andere Informationen uber
              den Prozess enthalt (siehe <sys/user.h>). Das >>word<< wird  als
              Ergebnis des ptrace()-Aufrufs zuruckgegeben. Typischerweise muss
              der Versatz am >>word<< ausgerichtet sein, obwohl dies  je  nach
              Architektur  variieren  kann.  Lesen Sie die ANMERKUNGEN. (daten
              wird ignoriert.)

       PTRACE_POKETEXT, PTRACE_POKEDATA
              kopiert das >>word<< daten an die Stelle adresse im Speicher des
              Kindprozesses.  Wie  oberhalb  sind  die beiden Abfragen derzeit
              gleichwertig.

       PTRACE_POKEUSER
              kopiert  das  >>word<<  daten  an   den   Versatz   adresse   im
              BENUTZERbereich des Kindprozesses. Wie oberhalb muss der Versatz
              am >>word<< ausgerichtet sein. Um  die  Integritat  des  Kernels
              aufrecht  zu erhalten, sind einige Anderungen in BENUTZERbereich
              nicht erlaubt.

       PTRACE_GETREGS, PTRACE_GETFPREGS
              kopiert die Mehrzweck-  beziehungsweise  FlieBpunktregister  des
              Kindprozesses  an  die  Stelle daten im Elternprozess. Lesen Sie
              <sys/user.h>, um Informationen uber das Format dieser  Daten  zu
              erhalten. (adresse wird ignoriert.)

       PTRACE_GETSIGINFO (seit Linux 2.3.99-pre6)
              ruft   Informationen   uber   das   Signal  ab,  das  den  Stopp
              verursachte.    Kopiert    eine    siginfo_t-Struktur     (siehe
              sigaction(2))   vom   Kindprozess   an   die   Stelle  daten  im
              Elternprozess. (adresse wird ignoriert.)

       PTRACE_SETREGS, PTRACE_SETFPREGS
              kopiert die Mehrzweck- beziehungsweise  FlieBpunktregister   des
              Kindprozessesan  die  Stelle  daten  im  Elternprozess.  Wie fur
              PTRACE_POKEUSER konnten einige Anderungen  am  Mehrzweckregister
              verboten sein. (adresse wird ignoriert.)

       PTRACE_SETSIGINFO (seit Linux 2.3.99-pre6)
              setzt  Signalinformationen.  Kopiert eine siginfo_t-Struktur von
              der Stelle daten vom Eltern-  zum  Kindprozess.  Dies  wird  nur
              Signale   betreffen,   die   normalerweise  an  den  Kindprozess
              zugestellt wurden und vom Verfolger abgefangen wurden. Es konnte
              schwierig   werden,   diese  normalen  Signale  von  kunstlichen
              Signalen zu unterscheiden, die  von  ptrace()  selbst  generiert
              wurden. (adresse wird ignoriert.)

       PTRACE_SETOPTIONS (seit Linux 2.4.6; siehe FEHLER fur caveats)
              setzt  Ptrace-Optionen von daten im Elternprozess. (adresse wird
              ignoriert.) daten  wird  als  Bit  in  der  Maske  der  Optionen
              interpretiert, die durch die folgenden Schalter angegeben wird:

              PTRACE_O_TRACESYSGOOD (seit Linux 2.4.6)
                     Wenn  Systemaufrufe  abgefangen werden, wird Bit 7 in der
                     Signalnummer gesetzt (d.h.(SIGTRAP  |  0x80)  geschickt).
                     Dies   erleichtert   es  dem  Verfolger  den  Unterschied
                     zwischen normalen abgefangenen Signalen  und  denen,  die
                     durch  einen Systemaufruf verursacht wurden, zu erkennen.
                     (PTRACE_O_TRACESYSGOOD funktioniert moglicherweise  nicht
                     auf allen Architekturen.)

              PTRACE_O_TRACEFORK (seit Linux 2.5.46)
                     stoppt  den  Kindprozess beim nachsten Aufruf von fork(2)
                     mit   SIGTRAP  |   PTRACE_EVENT_FORK << 8   und   startet
                     automatisch  die Verfolgung des neuen Prozesszweiges, der
                     mit  einem  SIGSTOP  starten  wird.  Die  PID  des  neuen
                     Prozesses kann mit PTRACE_GETEVENTMSG abgefragt werden.

              PTRACE_O_TRACEVFORK (seit Linux 2.5.46)
                     stoppt  den Kindprozess beim nachsten Aufruf von vfork(2)
                     mit  SIGTRAP  |   PTRACE_EVENT_VFORK << 8   und   startet
                     automatisch       die      Verfolgung      des      neuen
                     >>vfork<<-Prozesszweiges, der mit einem  SIGSTOP  starten
                     wird.    Die   PID   des   neuen   Prozesses   kann   mit
                     PTRACE_GETEVENTMSG abgefragt werden.

              PTRACE_O_TRACECLONE (seit Linux 2.5.46)
                     stoppt den Kindprozess beim nachsten clone(2)-Aufruf  mit
                     SIGTRAP | PTRACE_EVENT_CLONE << 8 und startet automatisch
                     die Verfolgung des neuen  geklonten  Prozesses,  der  mit
                     einem  SIGSTOP  starten wird. Die PID des neuen Prozesses
                     kann  mit  PTRACE_GETEVENTMSG  abgefragt  werden.   Diese
                     Option   kann  nicht  in  allen  Fallen  clone(2)-Aufrufe
                     abfangen. Falls der Kindprozess clone(2) mit dem Schalter
                     CLONE_VFORK  aufruft, wird stattdessen PTRACE_EVENT_VFORK
                     geschickt,   wenn   PTRACE_O_TRACEVFORK   gesetzt    ist;
                     andernfalls  wird  PTRACE_EVENT_FORK  geschickt, wenn der
                     Kindprozess  clone(2)  mit  dem  auf  SIGCHLD   gesetzten
                     Exit-Signal   aufgerufen  wird,  wenn  PTRACE_O_TRACEFORK
                     gesetzt ist.

              PTRACE_O_TRACEEXEC (seit Linux 2.5.46)
                     stoppt den Kindprozess beim nachsten execve(2)-Aufruf mit
                     SIGTRAP | PTRACE_EVENT_EXEC << 8.

              PTRACE_O_TRACEVFORKDONE (seit Linux 2.5.60)
                     stoppt   den  Kindprozess  beim  Abschluss  des  nachsten
                     vfork(2)-Aufrufs          mit          SIGTRAP          |
                     PTRACE_EVENT_VFORK_DONE << 8.

              PTRACE_O_TRACEEXIT (seit Linux 2.5.60)
                     stoppt   den  Kindprozess  beim  Beenden  mit  SIGTRAP  |
                     PTRACE_EVENT_EXIT << 8. Der Exit-Status des Kindprozesses
                     kann  mit  PTRACE_GETEVENTMSG  abgefragt  werden.  Dieser
                     Stopp findet fruh wahrend des Prozesses statt,  wenn  die
                     Register  noch  verfugbar  sind,  was  es  dem  Verfolger
                     ermoglicht zu sehen, wo  das  Beenden  veranlasst  wurdu,
                     wohingegen   die   normale   Benachrichtigung   uber  die
                     Beendigung geschickt wird, wenn der Prozess  das  Beenden
                     abgeschlossen  hat.  Auch wenn der Kontext verfugbar ist,
                     kann der Verfolger das Beenden an diesem Punkt nicht mehr
                     verhindern.

       PTRACE_GETEVENTMSG (seit Linux 2.5.46)
              eine  Nachricht  (als  unsigned  long)  uber das Ptrace-Ereignis
              abfragen, das einfach so auftrat und es an die Stelle  daten  im
              Elternprozess  platzieren.  Fur  PTRACE_EVENT_EXIT  ist dies der
              Exit-Status   des    Kindprozesses.    Fur    PTRACE_EVENT_FORK,
              PTRACE_EVENT_VFORK  und  PTRACE_EVENT_CLONE ist dies die PID des
              neuen Prozesses. Seit Linux 2.6.18 ist auch die  PID  des  neuen
              Prozesses  fur  PTRACE_EVENT_VFORK_DONE verfugbar. (adresse wird
              ignoriert.)

       PTRACE_CONT
              startet den gestoppten Kindprozess  erneut.  Falls  daten  nicht
              Null  und  nicht  SIGSTOP ist, wird es als Signal interpretiert,
              das an den Kindprozess geschickt  wird,  andernfalls  wird  kein
              Signal  geschickt.  Dadurch  kann der Elternprozess zum Beispiel
              steuern, ob ein Signal an den Kindprozess  geschickt  wird  oder
              nicht. (adresse wird ignoriert.)

       PTRACE_SYSCALL, PTRACE_SINGLESTEP
              startet   den   gestoppten   Kindprozess  wie  fur  PTRACE_CONT,
              arrangiert aber, dass der Kindprozess beim nachsten Eintrag oder
              einem  Systemaufruf  beziehungsweise  nach  der Ausfuhrung einer
              einzelnen Anweisung gestoppt wird. (Der Kindprozess  wird  auch,
              wie  ublich,  uber  den  Empfang  des Signals gestoppt.) Aus der
              Sicht des Elternprozesses scheint es, dass der Kindprozess durch
              Empfang eines SIGTRAP gestoppt wurde. Daher gibt es zum Beispiel
              fur PTRACE_SYSCALL die Idee, beim ersten Stopp die Argumente des
              Systemaufrufs  zu  prufen,  dann einen anderen PTRACE_SYSCALL zu
              schicken und den Ruckgabewert des Systemaufrufs am zweiten Stopp
              zu   prufen.   Das  Argument  daten  wird  wie  fur  PTRACE_CONT
              behandelt. (adresse wird ignoriert.)

       PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (seit Linux 2.6.14)
              fur PTRACE_SYSEMU beim nachsten Eintrag  fur  den  Systemaufruf,
              der   nicht   ausgefuhrt   wird,  fortfahren  und  stoppen.  Fur
              PTRACE_SYSEMU_SINGLESTEP das gleiche tun, aber in einem einzigen
              Schritt,  wenn  es  sich  nicht  um  einen Systemaufruf handelt.
              Dieser Aufruf wird  von  Programmen,  wie  >>User  Mode  Linux<<
              verwandt,  die  die  Systemaufrufe  des  Kindprozesses emulieren
              wollen. Das Argument daten wird wie fur  PTRACE_CONT  behandelt.
              (adresse   wird   ignoriert;   nicht   auf  allen  Architekturen
              unterstutzt.)

       PTRACE_KILL
              sendet dem Kindprozess ein SIGKILL, um ihn zu beenden.  (adresse
              und daten werden ignoriert.)

       PTRACE_ATTACH
              hangt  den  in pid angegebenen Prozess an und macht ihn zu einem
              verfolgten  >>Kindprozess<<  des  aufrufenden   Prozesses.   Das
              Verhalten  des  Kindprozesses  ist  wie  bei PTRACE_TRACEME. Der
              aufrufende  Prozess  bekommt  fur   die   meisten   Zwecke   den
              Elternprozess    des    Kindprozesses   (z.B.   wird   er   eine
              Benachrichtigung von Ereignissen des Kindprozesses erhalten  und
              in  der  Ausgabe  von  ps(1) als Elternprozess des Kindprozesses
              erscheinen), aber ein  getppid(2)  durch  den  Kindprozess  wird
              immer noch die PID des Original-Elternprozesses zuruckgeben. Dem
              Kindprozess wird ein  SIGSTOP  geschickt,  er  wird  aber  nicht
              notwendigerweise  bei  der  Komplettierung des Aufrufs gestoppt;
              benutzen Sie wait(2), um auf das Stoppen  des  Kindprozesses  zu
              warten. (adresse und daten werden ignoriert.)

       PTRACE_DETACH
              startet den gestoppten Kindprozess wie fur PTRACE_CONT, lost ihn
              aber zuerst vom  Prozess  ab,  indem  der  Ubernahme-Effekt  von
              PTRACE_ATTACH  und  die  Effekte  von  PTRACE_TRACEME ruckgangig
              gemacht werden. Obwohl dies vielleicht nicht  beabsichtigt  ist,
              kann  unter  Linux  ein  verfolgter  Kindprozess  auf  diese Art
              abgelost werden ohne Rucksicht darauf zu nehmen, welche  Methode
              zum   Starten   der   Verfolgung   benutzt  wurde.(adresse  wird
              ignoriert.)

R"UCKGABEWERT

       Bei Erfolg geben PTRACE_PEEK*-Anfragen die  angefragten  Daten  zuruck,
       wahrend  andere  Anfragen Null zuruckgeben. Bei einem Fehler geben alle
       Anfragen -1 zuruck und errno wird entsprechend gesetzt.  Da  der  Wert,
       der  von  einer erfolgreichen PTRACE_PEEK*-Anfrage zuruckgegeben wurde,
       -1 sein konnte, muss der Aufrufende nach solchen Anfragen errno prufen,
       um zu untersuchen, ob ein Fehler aufgetreten ist oder nicht.

FEHLER

       EBUSY  (nur  i386)  Es  ist  beim  Reservieren  oder der Freigabe eines
              Debug-Registers ein Fehler aufgetreten.

       EFAULT Es gab einen Versuch in einem ungultigen Bereich im Speicher des
              Eltern-   oder   Kindprozesses   zu  lesen  oder  zu  schreiben,
              wahrscheinlich, weil der Bereich nicht abgebildet war oder  kein
              Zugriff   moglich  war.  Unglucklicherweise  geben  unter  Linux
              mehrere Variationen dieser Storung mehr oder weniger willkurlich
              EIO oder EFAULT zuruck.

       EINVAL Es wurde versucht, eine ungultige Option zu setzen.

       EIO    abfrage  ist  ungultig,  es  wurde versucht, in einem ungultigen
              Bereich im Speicher des Eltern- oder Kindprozesses zu lesen oder
              zu  schreiben,  es  gab  eine  Verletzung der Ausrichtung an der
              >>word<<-GroBe oder es wurde wahrend des Neustarts  der  Abfrage
              ein ungultiges Signal angegeben.

       EPERM  Der  angegebene  Prozess kann nicht verfolgt werden. Dies konnte
              daher  ruhren,  dass  der   Elternprozess   uber   unzureichende
              Privilegien   verfugt   (die   Fahigkeit   CAP_SYS_PTRACE   wird
              benotigt);  unprivilegierte  Prozesse  konnen   keine   Prozesse
              verfolgen,  denen  sie  keine  Signale  senden  konnen  oder die
              SUID-/SGID-Programme ausfuhren, was naheliegend ist.  Alternativ
              konnte  der Prozess bereits verfolgt werden oder init(8) (PID 1)
              sein.

       ESRCH  Der angegebene Prozess exisitiert nicht, wird derzeit nicht  vom
              Aufrufenden  verfolgt oder ist nicht gestoppt (bei Anfragen, die
              dies erfordern).

KONFORM ZU

       SVr4, 4.3BSD.

ANMERKUNGEN

       Obwohl  Argumente  fur  ptrace()  gemaB  dem   angegebenen   Prototypen
       interpretiert  werden,  deklariert  Glibc  derzeit  ptrace()  als  eine
       variable Funktion mit nur dem festen anfrage-Argument.  Dies  bedeutet,
       dass  nicht  gewollte  anhangende Argumente weggelassen werden konnten,
       obwohl dies Gebrauch vom nicht dokumentierten gcc(1)-Verhalten macht.

       init(8), der Prozess mit  der  Prozessnummer  1,  kann  nicht  verfolgt
       werden.

       Das  Layout  des Speicherinhalts und des BENUTZERbereichs sind ziemlich
       von Betriebsystem und Architektur abhangig. Der  mitgelieferte  Versatz
       und  die zuruckgegebenen Daten konnten nicht ganz zu der Definition von
       struct user passen.

       Die  GroBe  eines  >>word<<  wird   durch   die   Betriebsystemvariante
       festgelegt (z.B. ist es fur ein 32-Bit-Linux 32 Bit, etc.).

       Verfolgung  bewirkt  ein  paar  feine  Unterschiede in der Semantik des
       verfolgenden Prozesses. Wenn ein Prozess zum Beispiel mit PTRACE_ATTACH
       angehangt   ist,   kann   dessen  Original-Elternprozess  nicht  langer
       Benachrichtigungen mittels wait(2) empfangen, wenn  er  stoppt  und  es
       gibt  effektiv  keine  Moglichkeit  fur  den  neuen Elternprozess diese
       Benachrichtigung zu simulieren.

       Wenn der  Elternprozess  ein  Ergeignis  mit  gesetztem  PTRACE_EVENT_*
       empfangt,     liegt     der     Kindprozess     nicht    im    normalen
       Signal-Lieferungspfad. Dies  bedeutet,  dass  der  Elternprozess  nicht
       ptrace(PTRACE_CONT) mit einem Signal oder ptrace(PTRACE_KILL) ausfuhren
       kann. Stattdessen kann kill(2) mit einem SIGKILL-Signal benutzt werden,
       um  den  Kindprozess  nach  dem  Empfang  einer  dieser  Nachrichten zu
       beenden.

       Diese Seite  dokumentiert  die  Moglichkeit,  wie  der  ptrace()-Aufruf
       derzeit  in  Linux  arbeitet.  Sein  Verhalten  unterscheidet  sich auf
       anderen UNIX-Geschmacksrichtungen deutlich.  Auf  jeden  Fall  ist  die
       Benutzung  von  ptrace()  in hohem Grad abhangig vom Betriebssystem und
       der Architektur.

       Die  SunOS-Handbuchseite  beschreibt  ptrace()  als  >>einzigartig  und
       geheimnisvoll<<,  was  es auch ist. Die proc-basierte Schnittstelle zur
       Fehlersuche   in   Solaris   2   implementiert   eine   Obermenge   von
       ptrace()-Funktionalitat in einer kraftigeren und einheitlicheren Art.

FEHLER

       Auf  Rechnern  mit  2.6  Kernel-Headern ist PTRACE_SETOPTIONS mit einem
       anderen Wert deklariert, als auf einem fur 2.4. Dies fuhrt  dazu,  dass
       Anwendungen,  die  mit  solchen  Headern  kompiliert  wurden,  bei  der
       Ausfuhrung auf 2.4er Kerneln scheitern. Dies kann  durch  Neudefinieren
       von  PTRACE_SETOPTIONS  zu  PTRACE_OLDSETOPTIONS  umgangen werden, wenn
       dies definiert ist.

SIEHE AUCH

       gdb(1), strace(1), execve(2),  fork(2),  signal(2),  wait(2),  exec(3),
       capabilities(7)

KOLOPHON

       Diese   Seite   ist   Teil   der  Veroffentlichung  3.32  des  Projekts
       Linux-man-pages. Eine Beschreibung des Projekts und Informationen,  wie
       Fehler     gemeldet     werden     konnen,     finden     sich    unter
       http://www.kernel.org/doc/man-pages/.

"UBERSETZUNG

       Die deutsche Ubersetzung dieser Handbuchseite wurde von Patrick  Rother
       <krd@gulu.net> und Chris Leick <c.leick@vollbio.de> erstellt.

       Diese  Ubersetzung  ist  Freie Dokumentation; lesen Sie die GNU General
       Public  License  Version  3  oder  neuer   bezuglich   der   Copyright-
       Bedingungen. Es wird KEINE HAFTUNG ubernommen.

       Wenn  Sie  Fehler  in  der  Ubersetzung  dieser  Handbuchseite  finden,
       schicken     Sie     bitte     eine     E-Mail     an     <debian-l10n-
       german@lists.debian.org>.

Linux                            30. Marz 2009                       PTRACE(2)