Provided by: manpages-fr-dev_3.27fr1.4-1_all bug

NOM

       ptrace - Suivre un processus

SYNOPSIS

       #include <sys/ptrace.h>

       long ptrace(enum __ptrace_request request, pid_t pid,
                   void *addr, void *data);

DESCRIPTION

       L'appel  systeme  ptrace()  fournit  au  processus  parent  un moyen de
       controler l'execution  d'un  autre  processus  et  d'editer  son  image
       memoire.    L'utilisation    primordiale    de   cette   fonction   est
       l'implementation de points d'arret pour le debogage, et pour suivre les
       appels systeme.

       Le  pere peut demarrer un suivi en appelant fork(2) et que le fils cree
       fasse un PTRACE_TRACEME, suivi (en general) par un exec(3).  Autrement,
       le  pere peut commencer un suivi sur un processus existant en utilisant
       PTRACE_ATTACH.

       Le processus fils suivi s'arretera a chaque fois qu'un signal lui  sera
       delivre,  meme  si le signal est ignore (a l'exception de SIGKILL qui a
       les effets habituels). Le pere sera prevenu a son prochain  wait(2)  et
       pourra  inspecter  et  modifier le processus fils pendant son arret. Le
       parent  peut  egalement  faire  continuer  l'execution  de  son   fils,
       eventuellement  en  ignorant  le  signal  ayant  declenche  l'arret, ou
       envoyant un autre signal.

       Quand le  pere  a  fini  le  suivi,  il  peut  terminer  le  fils  avec
       PTRACE_KILL   ou  le  faire  continuer  normalement,  non  suivi,  avec
       PTRACE_DETACH.

       La  valeur  de  l'argument  request  indique  precisement  l'action   a
       entreprendre.

       PTRACE_TRACEME
              Le  processus  en  cours va etre suivi par son pere. Tout signal
              (sauf SIGKILL) recu par le processus l'arretera, et le pere sera
              notifie  grace  a  wait(2).  De  plus,  les  appels ulterieurs a
              execve(2) par ce processus lui enverront SIGTRAP, ce  qui  donne
              au  pere  la  possibilite  de reprendre le controle avant que le
              nouveau programme continue son execution. Un processus  ne  doit
              pas  envoyer  cette  requete  si  son  pere  n'est pas pret a le
              suivre. Dans cette requete pid, addr, et data sont ignores.

       La requete ci-dessus ne sert que dans le processus fils. Les autres  ne
       servent  que dans le pere. Par la suite, pid precise le fils sur lequel
       agir. Pour les requetes autres  que  PTRACE_KILL,  le  fils  doit  etre
       arrete.

       PTRACE_PEEKTEXT, PTRACE_PEEKDATA
              Lire  un  mot  a l'adresse addr dans l'espace memoire du fils et
              renvoyer la valeur en resultat de ptrace(). Linux ne separe  pas
              les  espaces  d'adressage  de code et de donnees, ainsi ces deux
              requetes sont equivalentes. L'argument data est ignore.

       PTRACE_PEEKUSER
              Lire un mot a l'adresse addr dans l'espace  USER  du  fils,  qui
              contient les registres et diverses informations sur le processus
              (voir <sys/user.h>). La  valeur  est  renvoyee  en  resultat  de
              ptrace().  En  principe,  l'adresse  doit  etre  alignee sur une
              frontiere de mots, bien que cela varie selon les  architectures.
              Consultez la section NOTES. data est ignore.

       PTRACE_POKETEXT, PTRACE_POKEDATA
              Copier  un  mot depuis l'adresse data de la memoire du pere vers
              l'adresse addr de la memoire du fils.  Comme  precedemment,  les
              deux requetes sont equivalentes.

       PTRACE_POKEUSER
              Copier  un  mot  depuis l'emplacement data de la memoire du pere
              vers l'emplacement addr dans l'espace USER  du  processus  fils.
              Comme  plus  haut, les emplacements doivent etre alignes sur une
              frontiere de mot. Pour maintenir l'integrite du noyau, certaines
              modifications de la zone USER sont interdites.

       PTRACE_GETREGS, PTRACE_GETFPREGS
              Copier  les  registres  generaux  ou  du  processeur  en virgule
              flottante, vers l'adresse data du pere.  Consultez  <sys/user.h>
              pour les details sur le format des donnees (addr est ignore).

       PTRACE_GETSIGINFO (depuis Linux 2.3.99-pre6)
              Recuperer  des  informations  sur le signal qui a cause l'arret.
              Pour  ce  faire,  copier  une  structure  siginfo_t   (consultez
              sigaction(2))  du fils a l'adresse data du pere. L'argument addr
              est ignore.

       PTRACE_SETREGS, PTRACE_SETFPREGS
              Remplir les registres  generaux  ou  du  processeur  en  virgule
              flottante,  depuis  le  contenu de l'adresse data du pere. Comme
              pour PTRACE_POKEUSER certaines  modifications  sont  interdites.
              (addr est ignore).

       PTRACE_SETSIGINFO (depuis Linux 2.3.99-pre6)
              Fixer   des   informations  de  signaux.  Copier  une  structure
              siginfo_t de l'adresse data dans le  pere  vers  le  fils.  Cela
              n'affecte  que les signaux qui auraient du etre delivres au fils
              et ont ete  interceptes  a  cause  de  ptrace().  Il  peut  etre
              difficile  de  differencier  ces  signaux  normaux  des  signaux
              generes par ptrace() lui-meme. L'argument addr est ignore.

       PTRACE_SETOPTIONS (depuis Linux 2.4.6, voir remarques dans BOGUES)
              Fixe les options de ptrace a partir de l'adresse  data  dans  le
              pere  (addr  est  ignore).  data  est interprete comme un masque
              d'options, qui est construit a partir des drapeaux suivants :

              PTRACE_O_TRACESYSGOOD (Depuis Linux 2.4.6)
                     Lors d'un appel systeme, mettre a 1 le bit 7 du numero de
                     signal  (envoyer  SIGTRAP|0x80). Cela permet au processus
                     utilisant ptrace()  de  faire  la  difference  entre  une
                     trappe  normale,  et  une  trappe due a un appel systeme.
                     PTRACE_O_TRACESYSGOOD peut ne pas marcher sur toutes  les
                     architectures.

              PTRACE_O_TRACEFORK (depuis Linux 2.5.46)
                     Arreter  le  fils  au  prochain  fork(2)  avec  SIGTRAP |
                     PTRACE_EVENT_FORK << 8  et  commencer  automatiquement  a
                     suivre  le  nouveau processus cree, qui demarrera avec un
                     signal SIGSTOP. Le PID du  nouveau  processus  peut  etre
                     recupere avec PTRACE_GETEVENTMSG.

              PTRACE_O_TRACEVFORK (depuis Linux 2.5.46)
                     Arreter le fils au prochain appel vfork(2) avec SIGTRAP |
                     PTRACE_EVENT_VFORK << 8 et  commencer  automatiquement  a
                     suivre  le  nouveau processus cree, qui demarrera avec un
                     signal SIGSTOP. Le PID du  nouveau  processus  peut  etre
                     obtenu avec PTRACE_GETEVENTMSG.

              PTRACE_O_TRACECLONE (depuis Linux 2.5.46)
                     Arreter le fils au prochain appel clone(2) avec SIGTRAP |
                     PTRACE_EVENT_CLONE << 8 et  commencer  automatiquement  a
                     suivre  le nouveau processus clone, qui demarrera avec un
                     signal SIGSTOP. Le PID du  nouveau  processus  peut  etre
                     obtenu  avec PTRACE_GETEVENTMSG. Cette option peut ne pas
                     intercepter tous les appels clone(2). Si le fils  appelle
                     clone(2)  avec l'attribut CLONE_VFORK, PTRACE_EVENT_VFORK
                     sera envoye si PTRACE_O_TRACEVFORK est utilise. Sinon, si
                     le  fils  appelle  clone(2)  avec SIGCHLD comme signal de
                     terminaison,    PTRACE_EVENT_FORK    sera    envoye    si
                     PTRACE_O_TRACEFORK est utilise.

              PTRACE_O_TRACEEXEC (depuis Linux 2.5.46)
                     Arreter  le fils au prochain appel execve(2) avec SIGTRAP
                     | PTRACE_EVENT_EXEC << 8.

              PTRACE_O_TRACEVFORKDONE (depuis Linux 2.5.60)
                     Arreter le fils  a  la  fin  du  prochain  vfork(2)  avec
                     SIGTRAP | PTRACE_EVENT_VFORK_DONE << 8.

              PTRACE_O_TRACEEXIT (depuis Linux 2.5.60)
                     Arreter   le   fils  a  sa  terminaison  avec  SIGTRAP  |
                     PTRACE_EVENT_EXIT << 8. Le code de retour  du  fils  peut
                     etre  obtenu  avec  PTRACE_GETEVENTMSG.  Cet  arret  sera
                     effectue tot dans la terminaison du processus, alors  que
                     les registres sont toujours disponibles, ce qui permet au
                     processus utilisant ptrace() de voir  ou  la  terminaison
                     s'est  produite, alors que la notification de terminaison
                     normale a lieu a la fin de cette terminaison. Meme si  le
                     contexte  est disponible, l'appelant ne peut pas empecher
                     la terminaison du fils.

       PTRACE_GETEVENTMSG (depuis Linux 2.5.46)
              Recuperer  un  message  (dans  un  unsigned   long)   concernant
              l'evenement   ptrace  qui  vient  d'arriver,  en  le  placant  a
              l'adresse data dans le pere. Pour PTRACE_EVENT_EXIT,  il  s'agit
              du   code   de   retour   du   fils.   Pour   PTRACE_EVENT_FORK,
              PTRACE_EVENT_VFORK et PTRACE_EVENT_CLONE, il s'agit  du  PID  du
              nouveau  processus.  Depuis  Linux  2.6.18,  le  PID  du nouveau
              processus est egalement disponible pour PTRACE_EVENT_VFORK_DONE.
              (addr est ignore.)

       PTRACE_CONT
              Redemarrer  le  processus  fils  arrete.  Si data est non nul et
              autre que SIGSTOP, il est interprete comme un numero de signal a
              delivrer  au  fils ;  sinon  aucun signal n'est delivre. On peut
              ainsi controler si un  signal  envoye  au  fils  doit  lui  etre
              delivre ou non (addr est ignore).

       PTRACE_SYSCALL, PTRACE_SINGLESTEP
              Redemarrer le processus fils arrete comme pour PTRACE_CONT, mais
              en s'arrangeant pour qu'il soit arrete a la prochaine entree  ou
              sortie  d'un  appel  systeme, ou apres la prochaine instruction,
              respectivement. (Le fils sera aussi arrete  par  l'arrivee  d'un
              signal).  Du  point de vue du pere, le fils semblera etre arrete
              par SIGTRAP. Ainsi, pour PTRACE_SYSCALL l'idee  est  d'inspecter
              les  arguments de l'appel systeme au premier arret puis de faire
              un autre PTRACE_SYSCALL et d'inspecter la valeur  de  retour  au
              second  arret.  Le  parametre  data  est  interprete  comme pour
              PTRACE_CONT. (addr est ignore).

       PTRACE_SYSEMU, PTRACE_SYSEMU_SINGLESTEP (depuis Linux 2.6.14)
              Pour PTRACE_SYSEMU, continuer puis s'arreter  lors  du  prochain
              appel    systeme,    qui    ne    sera    pas    execute.   Pour
              PTRACE_SYSEMU_SINGLESTEP, faire la meme chose, mais executer pas
              a  pas s'il ne s'agit pas d'un appel systeme. Cette fonction est
              utilisee par des programmes comme User Mode Linux,  qui  veulent
              emuler  tous  les  appels systeme du fils. Le parametre data est
              interprete comme pour PTRACE_CONT. (addr est ignore ; cet  appel
              n'est pas disponible sur toutes les architectures.)

       PTRACE_KILL
              Envoyer  au  fils  un  signal SIGKILL pour le terminer. (addr et
              data sont ignores).

       PTRACE_ATTACH
              Attacher  le  processus  numero  pid,   pour   le   suivre.   Le
              comportement  du  fils  est  le  meme  que  s'il  avait  fait un
              PTRACE_TRACEME. Le processus appelant devient alors le pere pour
              de nombreuses choses (il recevra les notifications d'evenements,
              et sera indique comme le pere dans un  ps(1)).  Mais  getppid(2)
              renverra  dans le fils le PID du vrai pere. Le processus fils va
              recevoir un SIGSTOP, mais il ne sera peut-etre pas  stoppe  tout
              de suite, utilisez wait(2) pour attendre son arret (addr et data
              sont ignores).

       PTRACE_DETACH
              Relancer un processus fils comme avec PTRACE_CONT, en commencant
              par  le  detacher,  ce  qui  annule  les effets de changement de
              parente de PTRACE_ATTACH et les  effets  de  PTRACE_TRACEME.  Le
              processus  ne  sera plus suivi. Bien que cela soit involontaire,
              sous Linux un processus suivi peut etre  detache  ainsi  quelque
              soit  la  methode  employee  pour  demarrer  le suivi. (addr est
              ignore).

VALEUR RENVOY'EE

       Pour les requetes PTRACE_PEEK*, ptrace() renvoie la valeur reclamee  et
       zero  pour  les  autres  requetes,  ou -1 en cas d'echec en remplissant
       errno avec le code d'erreur. Comme la valeur renvoyee par  une  requete
       PTRACE_PEEK* peut legitimement etre -1, il faut verifier errno apres un
       tel appel pour verifier si une erreur s'est produite.

ERREURS

       EBUSY  (i386 seulement) Il y a eu une erreur lors de l'allocation ou de
              la liberation d'un registre de debogage.

       EFAULT Tentative  de  lire  ou ecrire dans une zone memoire invalide du
              processus fils ou  du  pere,  probablement  parce  que  la  zone
              n'etait  pas projetee ou accessible. Malheureusement sous Linux,
              certaines variantes de cette erreur declencheront EIO ou  EFAULT
              plus ou moins arbitrairement.

       EINVAL Tentative d'utiliser une option invalide.

       EIO    La  requete request n'est pas valide ou une tentative de lecture
              ou d'ecriture dans une zone invalide de memoire a  eu  lieu.  Il
              peut   egalement  y  avoir  un  probleme  d'alignement  sur  une
              frontiere de mot, ou une tentative de redemarrage en envoyant un
              signal invalide.

       EPERM  Le processus indique ne peut pas etre suivi. Cela peut etre du a
              un manque de privilege du parent  (la  capacite  necessaire  est
              CAP_SYS_PTRACE).  Les  processus  non privilegies ne peuvent pas
              suivre les processus auxquels ils ne peuvent envoyer de  signal,
              ou  ceux qui s'executent Set-UID/Set-GID. En outre, le processus
              vise peut etre deja suivi, ou etre init(8) (pid 1).

       ESRCH  Le processus indique  n'existe  pas,  ou  n'est  pas  suivi  par
              l'appelant,  ou  n'est  pas arrete (pour les requetes qui en ont
              besoin).

CONFORMIT'E

       SVr4, BSD 4.3.

NOTES

       Bien que les arguments de ptrace() soient  interpretes  comme  dans  le
       prototype  plus  haut,  la  bibliotheque glibc declare ptrace comme une
       fonction variadique ou seul l'argument request est fixe. Ceci  signifie
       que  les  arguments  finaux  inutiles  peuvent etre omis, bien que cela
       utilise un comportement non documente de gcc(1).

       init(8), le processus numero 1, ne peut pas etre suivi.

       La disposition du contenu de la memoire et de la zone USER dependent du
       systeme  d'exploitation et de l'architecture. Le decalage fourni et les
       donnees renvoyees peuvent  ne  pas  correspondre  entierement  avec  la
       definition d'une structure struct user.

       La  taille  d'un  mot  (<< word >>)  est  determinee  par la version du
       systeme d'exploitation (par exemple 32 bits pour Linux-32-bits, etc.)

       Le  suivi  peut  engendrer   des   modifications   subtiles   dans   le
       fonctionnement  du  processus. Par exemple, si un processus est attache
       avec PTRACE_ATTACH,  son  pere  original  ne  peut  plus  recevoir  les
       notifications avec wait(2) lorsqu'il s'arrete, et il n'y a pas de moyen
       de simuler cette notification.

       Lorsque le parent recoit un evenement avec  PTRACE_EVENT_*  active,  le
       fils  n'est  pas dans la procedure normale de reception de signal. Cela
       signifie que le parent ne peut pas executer ptrace(PTRACE_CONT) avec un
       signal  ou  ptrace(PTRACE_KILL).  kill(2)  avec  un signal SIGKILL peut
       cependant etre utilise pour tuer le processus fils a la reception  d'un
       de ces messages.

       Cette  page  documente le fonctionnement actuel de ptrace() sous Linux.
       Celui-ci peut varier sensiblement sur d'autres types d'Unix.  De  toute
       facon,  l'utilisation de ptrace() depend fortement de l'architecture et
       du systeme d'exploitation.

       La page de manuel de SunOS  decrit  ptrace()  comme  un  appel  systeme
       << unique  and  arcane >>,  ce qu'il est. Le mecanisme de debogage base
       sur le systeme proc, present dans Solaris 2 implemente  un  surensemble
       des  fonctionnalites  de  ptrace()  de  maniere  plus puissante et plus
       uniforme.

BOGUES

       Sur les machines ayant des en-tetes du noyau 2.6, PTRACE_SETOPTIONS est
       declare  avec  une valeur differente de celle du noyau 2.4. De ce fait,
       les applications compilees avec ces en-tetes ne peuvent pas  s'executer
       sous  des noyaux 2.4. Il est possible de contourner cette difficulte en
       redefinissant  PTRACE_SETOPTIONS  a  PTRACE_OLDSETOPTIONS,   si   cette
       derniere constante est definie.

VOIR AUSSI

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

COLOPHON

       Cette page fait partie de  la  publication  3.27  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      etre       trouvees       a       l'adresse
       <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

       Depuis  2010,  cette  traduction est maintenue a l'aide de l'outil po4a
       <URL:http://po4a.alioth.debian.org/>   par   l'equipe   de   traduction
       francophone        au        sein        du       projet       perkamon
       <URL:http://perkamon.alioth.debian.org/>.

       Christophe Blaess  <URL:http://www.blaess.fr/christophe/>  (1996-2003),
       Alain   Portal  <URL:http://manpagesfr.free.fr/>  (2003-2006).   Julien
       Cristau et l'equipe francophone de traduction de Debian (2006-2009).

       Veuillez  signaler  toute  erreur   de   traduction   en   ecrivant   a
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous pouvez toujours avoir acces a la version anglaise de  ce  document
       en utilisant la commande << man -L C <section> <page_de_man> >>.