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

BEZEICHNUNG

       ptrace - Prozessverfolgung

ÜBERSICHT

       #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 Ausführung eines  anderen  Prozesses  beobachten  und
       steuern  kann und sein Kernel-Abbild sowie die Register untersuchen und
       ändern 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  ausführt,  was
       (üblicherweise)  von  einem  exec(3)  gefolgt wird. Alternativ kann der
       Elternprozess die  Verfolgung  eines  existierenden  Prozesses  mittels
       PTRACE_ATTACH beginnen.

       Während  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  nächsten  wait(2)  benachrichtigt  und
       könnte  den  Kindprozess prüfen und verändern, während er gestoppt ist.
       Der Elternprozess veranlasst den Kindprozess anschließend  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  (außer  SIGKILL),  das  an  diesen Prozess
              gesandt wird, wird ihn stoppen und seinen Elternprozess  mittels
              wait(2)   benachrichtigen.  Außerdem  werden  alle  nachrangigen
              Aufrufe von execve(2) durch diesen Prozess  bewirken,  dass  ihm
              ein  SIGTRAP  gesandt wird, das es dem Elternprozess ermöglicht,
              die Kontrolle darüber  zu  erlangen,  bevor  das  neue  Programm
              ausgeführt 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 übrigen
       werden nur vom Elternprozess benutzt. In den  folgenden  Anfragen  gibt
       pid  den  Kindprozess  an,  auf  den eingewirkt werden soll. Für 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 zurück. Linux hat keine  separaten  Adressräume
              für  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 über
              den Prozess enthält (siehe <sys/user.h>). Das  »word«  wird  als
              Ergebnis des ptrace()-Aufrufs zurückgegeben. 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  Integrität  des  Kernels
              aufrecht  zu erhalten, sind einige Änderungen in BENUTZERbereich
              nicht erlaubt.

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

       PTRACE_GETSIGINFO (seit Linux 2.3.99-pre6)
              ruft   Informationen   über   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  Fließpunktregister   des
              Kindprozessesan  die  Stelle  daten  im  Elternprozess.  Wie für
              PTRACE_POKEUSER könnten einige Änderungen  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 würden und vom Verfolger abgefangen wurden. Es könnte
              schwierig   werden,   diese  normalen  Signale  von  künstlichen
              Signalen zu unterscheiden, die  von  ptrace()  selbst  generiert
              wurden. (adresse wird ignoriert.)

       PTRACE_SETOPTIONS (seit Linux 2.4.6; siehe FEHLER für 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 möglicherweise  nicht
                     auf allen Architekturen.)

              PTRACE_O_TRACEFORK (seit Linux 2.5.46)
                     stoppt  den  Kindprozess beim nächsten 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 nächsten 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 nächsten 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  Fällen  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 nächsten execve(2)-Aufruf mit
                     SIGTRAP | PTRACE_EVENT_EXEC << 8.

              PTRACE_O_TRACEVFORKDONE (seit Linux 2.5.60)
                     stoppt   den  Kindprozess  beim  Abschluss  des  nächsten
                     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 früh während des Prozesses statt,  wenn  die
                     Register  noch  verfügbar  sind,  was  es  dem  Verfolger
                     ermöglicht zu sehen, wo  das  Beenden  veranlasst  wurdu,
                     wohingegen   die   normale   Benachrichtigung   über  die
                     Beendigung geschickt wird, wenn der Prozess  das  Beenden
                     abgeschlossen  hat.  Auch wenn der Kontext verfügbar ist,
                     kann der Verfolger das Beenden an diesem Punkt nicht mehr
                     verhindern.

       PTRACE_GETEVENTMSG (seit Linux 2.5.46)
              eine  Nachricht  (als  unsigned  long)  über das Ptrace-Ereignis
              abfragen, das einfach so auftrat und es an die Stelle  daten  im
              Elternprozess  platzieren.  Für  PTRACE_EVENT_EXIT  ist dies der
              Exit-Status   des    Kindprozesses.    Für    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  für  PTRACE_EVENT_VFORK_DONE verfügbar. (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  für  PTRACE_CONT,
              arrangiert aber, dass der Kindprozess beim nächsten Eintrag oder
              einem  Systemaufruf  beziehungsweise  nach  der Ausführung einer
              einzelnen Anweisung gestoppt wird. (Der Kindprozess  wird  auch,
              wie  üblich,  über  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
              für PTRACE_SYSCALL die Idee, beim ersten Stopp die Argumente des
              Systemaufrufs  zu  prüfen,  dann einen anderen PTRACE_SYSCALL zu
              schicken und den Rückgabewert des Systemaufrufs am zweiten Stopp
              zu   prüfen.   Das  Argument  daten  wird  wie  für  PTRACE_CONT
              behandelt. (adresse wird ignoriert.)

       PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (seit Linux 2.6.14)
              für PTRACE_SYSEMU beim nächsten Eintrag  für  den  Systemaufruf,
              der   nicht   ausgeführt   wird,  fortfahren  und  stoppen.  Für
              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 für  PTRACE_CONT  behandelt.
              (adresse   wird   ignoriert;   nicht   auf  allen  Architekturen
              unterstützt.)

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

       PTRACE_ATTACH
              hängt  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  für   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 zurückgeben. 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 für PTRACE_CONT, löst ihn
              aber zuerst vom  Prozess  ab,  indem  der  Übernahme-Effekt  von
              PTRACE_ATTACH  und  die  Effekte  von  PTRACE_TRACEME rückgängig
              gemacht werden. Obwohl dies vielleicht nicht  beabsichtigt  ist,
              kann  unter  Linux  ein  verfolgter  Kindprozess  auf  diese Art
              abgelöst werden ohne Rücksicht darauf zu nehmen, welche  Methode
              zum   Starten   der   Verfolgung   benutzt  wurde.(adresse  wird
              ignoriert.)

RÜCKGABEWERT

       Bei Erfolg geben PTRACE_PEEK*-Anfragen die  angefragten  Daten  zurück,
       während  andere  Anfragen Null zurückgeben. Bei einem Fehler geben alle
       Anfragen -1 zurück und errno wird entsprechend gesetzt.  Da  der  Wert,
       der  von  einer erfolgreichen PTRACE_PEEK*-Anfrage zurückgegeben wurde,
       -1 sein könnte, muss der Aufrufende nach solchen Anfragen errno prüfen,
       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 ungültigen Bereich im Speicher des
              Eltern-   oder   Kindprozesses   zu  lesen  oder  zu  schreiben,
              wahrscheinlich, weil der Bereich nicht abgebildet war oder  kein
              Zugriff   möglich  war.  Unglücklicherweise  geben  unter  Linux
              mehrere Variationen dieser Störung mehr oder weniger willkürlich
              EIO oder EFAULT zurück.

       EINVAL Es wurde versucht, eine ungültige Option zu setzen.

       EIO    abfrage  ist  ungültig,  es  wurde versucht, in einem ungültigen
              Bereich im Speicher des Eltern- oder Kindprozesses zu lesen oder
              zu  schreiben,  es  gab  eine  Verletzung der Ausrichtung an der
              »word«-Größe oder es wurde während des Neustarts der Abfrage ein
              ungültiges Signal angegeben.

       EPERM  Der  angegebene  Prozess kann nicht verfolgt werden. Dies könnte
              daher  rühren,  dass  der   Elternprozess   über   unzureichende
              Privilegien   verfügt   (die   Fähigkeit   CAP_SYS_PTRACE   wird
              benötigt);  unprivilegierte  Prozesse  können   keine   Prozesse
              verfolgen,  denen  sie  keine  Signale  senden  können  oder die
              SUID-/SGID-Programme ausführen, was naheliegend ist.  Alternativ
              könnte  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  für  ptrace()  gemäß  dem   angegebenen   Prototypen
       interpretiert  werden,  deklariert  Glibc  derzeit  ptrace()  als  eine
       variable Funktion mit nur dem festen anfrage-Argument.  Dies  bedeutet,
       dass  nicht  gewollte  anhängende Argumente weggelassen werden könnten,
       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 abhängig. Der  mitgelieferte  Versatz
       und  die zurückgegebenen Daten könnten nicht ganz zu der Definition von
       struct user passen.

       Die Größe eines »word« wird durch die Betriebsystemvariante  festgelegt
       (z.B. ist es für 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
       angehängt   ist,   kann   dessen  Original-Elternprozess  nicht  länger
       Benachrichtigungen mittels wait(2) empfangen, wenn  er  stoppt  und  es
       gibt  effektiv  keine  Möglichkeit  für  den  neuen Elternprozess diese
       Benachrichtigung zu simulieren.

       Wenn der  Elternprozess  ein  Ergeignis  mit  gesetztem  PTRACE_EVENT_*
       empfängt,     liegt     der     Kindprozess     nicht    im    normalen
       Signal-Lieferungspfad. Dies  bedeutet,  dass  der  Elternprozess  nicht
       ptrace(PTRACE_CONT) mit einem Signal oder ptrace(PTRACE_KILL) ausführen
       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  Möglichkeit,  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 abhängig 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()-Funktionalität in einer kräftigeren und einheitlicheren Art.

FEHLER

       Auf  Rechnern  mit  2.6  Kernel-Headern ist PTRACE_SETOPTIONS mit einem
       anderen Wert deklariert, als auf einem für 2.4. Dies führt  dazu,  dass
       Anwendungen,  die  mit  solchen  Headern  kompiliert  wurden,  bei  der
       Ausführung 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  Veröffentlichung  3.32  des  Projekts
       Linux-man-pages. Eine Beschreibung des Projekts und Informationen,  wie
       Fehler     gemeldet     werden     können,     finden     sich    unter
       http://www.kernel.org/doc/man-pages/.

ÜBERSETZUNG

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

       Diese  Übersetzung  ist  Freie Dokumentation; lesen Sie die GNU General
       Public  License  Version  3  oder  neuer   bezüglich   der   Copyright-
       Bedingungen. Es wird KEINE HAFTUNG übernommen.

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