Provided by: manpages-es_1.55-8_all bug

NOMBRE

       ptrace - rastreo de un proceso

SINOPSIS

       #include <sys/ptrace.h>

       long  ptrace(enum  __ptrace_request  petici√n,  pid_t pid, void *direc,
       void *datos);

DESCRIPCI√ďN

       La llamada al sistema ptrace proporciona un medio por el que un proceso
       padre  puede  observar  y  controlar  la  ejecución  de  otro proceso y
       examinar  y  cambiar  su  imagen  de  memoria  y  registros.   Se   usa
       principalmente en la implementación de depuración con puntos de ruptura
       y en el rastreo de llamadas al sistema.

       El padre puede inicar un rastreo llamando a  fork(2)  haciendo  que  el
       hijo  restultante  realice un PTRACE_TRACEME, seguido (normalmente) por
       un exec(3).  Alternativamente, el padre puede comenzar  a  rastrear  un
       proceso existente usando PTRACE_ATTACH.

       Mientras est√° siendo rastreado, el hijo se detendr√° cada vez que reciba
       una se√Īal, aun cuando la se√Īal  se  haya  ignorado.  (La  excepci√≥n  es
       SIGKILL  que  tiene  su efecto habitual.) El padre ser√° informado en su
       siguiente wait(2) y puede inspeccionar  y  modificar  el  proceso  hijo
       mientras está parado.  A continuación, el padre puede hacer que el hijo
       contin√ļe,  ignorando  opcionalmente  la  se√Īal  recibida   (o   incluso
       entregando una se√Īal distinta en su lugar).  Cuando el padre termina de
       rastrear, puede terminar el hijo con PTRACE_KILL o hace que se contin√ļe
       ejecutando en un modo normal sin rastreo mediante PTRACE_DETACH.

       El valor del argumento petici√n determina la acci√≥n a realizar:

       PTRACE_TRACEME
              Indica  que  este  proceso  va  a  ser  rastreado  por su padre.
              Cualquier se√Īal (excepto SIGKILL) entregada a este proceso  har√°
              que  se  pare y su padre será informado mediante wait.  También,
              cualquier llamada posterior a exec realizada  por  este  proceso
              hará  que  se le envíe un SIGTRAP, dando al padre la posibilidad
              de obtener el control antes de que el nuevo programa comience su
              ejecución.  Probablemente,  un  proceso  no  debería  hacer esta
              petición si su padre no está esperando para  rastrearlo.   (pid,
              direc y datos se ignoran.)

       La petición anterior la usa sólo el proceso hijo. El resto las usa sólo
       el padre. En las siguientes peticiones,  pid  indica  el  proceso  hijo
       sobre  el  que se actuar√°. Para peticiones distintas de PTRACE_KILL, el
       proceso hijo debe estar parado.

       PTRACE_PEEKTEXT, PTRACE_PEEKDATA
              Lee una palabra de la posición direc.

       PTRACE_PEEKUSER
              Lee una palabra en el desplazamiento direc  del  √°rea  USER  del
              hijo,  que  contiene  los  registros y otra información sobre el
              proceso (vea  <linux/user.h>  y  <sys/user.h>).  La  palabra  se
              devuelve  como  resultado de la llamada ptrace.  Típicamente, el
              desplazamiento debe est√° alineado en una  frontera  de  palabra,
              aunque  esto  podría  variar  en  cada  arquitectura.  (datos se
              ignora).

       PTRACE_POKETEXT, PTRACE_POKEDATA
              Copia una palabra de la posición datos a la posición direc de la
              memoria del hijo. Como antes, las dos peticiones son actualmente
              equivalentes.

       PTRACE_POKEUSER
              Copia una palabra de la posición datos al  desplazamiento  direc
              en  el √°rea USER del hijo. Al igual que antes, el desplazamiento
              debe estar típicamente alineado en una frontera de palabra. Para
              conservar  la  integridad  del n√ļcleo, algunas modificaciones al
              √°rea USER se encuentran deshabilitadas.

       PTRACE_GETREGS, PTRACE_GETFPREGS
              Copia los registros de propósito general o de punto flotante del
              hijo,  respectivamente,  a  la  posición  datos  del  padre. Vea
              <linux/user.h> para obtener  información  sobre  el  formato  de
              estos datos. (direc se ignora.)

       PTRACE_SETREGS, PTRACE_SETFPREGS
              Copia los registros de propósito general o de punto flotante del
              hijo, respectivamente, desde la posición  datos  del  padre.  Al
              igual  que  para  PTRACE_POKEUSER,  alguna modificaciones de los
              registros de  propósito  general  pueden  estar  deshabilitadas.
              (direc se ignora.)

       PTRACE_CONT
              Reinicia  el  proceso hijo parado. Si datos no es cero y tampoco
              SIGSTOP se interpreta como una se√Īal que se entregar√°  al  hijo.
              En  otro caso, no se entrega ninguna se√Īal. As√≠, por ejemplo, el
              padre puede controlar si una se√Īal enviada al hijo es  entregada
              o no. (direc se ignora.)

       PTRACE_SYSCALL, PTRACE_SINGLESTEP
              Reinicia  el  proceso  hijo parado al igual que PTRACE_CONT pero
              prepara al hijo para que se pare en la  siguiente  entrada  a  o
              salida de una llamda al sistema o tras la ejecuci√≥n de una √ļnica
              intrucción, respectivamente. (Como es usual, el hijo también  se
              detendr√°  al recibir una se√Īal). Desde la perspectiva del padre,
              el hijo aparecer√° como si se hubiera  detenido  al  recibir  una
              se√Īal  SIGTRAP. Por lo que, por ejemplo, para PTRACE_SYSCALL, la
              idea es inspeccionar los argumentos de la llamada al sistema  en
              la primera parada, realizar a continuación otra PTRACE_SYSCALL e
              inspeccionar los valores devueltos por  la  llamada  al  sistema
              cuando se detenga la segunda vez. (direc se ignora.)

       PTRACE_KILL
              Env√≠a al hijo una se√Īal SIGKILL para que termine. (direc y datos
              se ignoran.)

       PTRACE_ATTACH
              Ata al proceso especificado en pid, convirtiéndolo en un  "hijo"
              rastreado.  El  hijo  se  comporta  como si hubiera realizado un
              PTRACE_TRACEME.  El proceso actual realmente se convierte en  el
              padre  del  proceso  hijo  para  la  mayoría  de propósitos (por
              ejemplo,  recibirá  notificación  de  los  eventos  del  hijo  y
              aparecer√°  en  la  salida de ps(1) como padre del hijo), pero un
              getppid(2) por parte del hijo todavía devolverá el pid del padre
              original.  Al  hijo se le envía un SIGSTOP pero, necesariamente,
              no tiene  por  qué  haberse  parado  cuando  esta  llamada  haya
              terminado. Use wait para esperar a que el hijo se pare. (direc y
              datos se ignoran.)

       PTRACE_DETACH
              Reinicia el hijo parado al igual que PTRACE_CONT pero primero lo
              desata  del  proceso,  deshaciendo  el efecto de reparentesco de
              PTRACE_ATTACH y los efectos de PTRACE_TRACEME.  Aunque quiz√°s no
              sea  intencionado,  bajo  Linux  un  proceso rastreado puede ser
              desatado de esta manera sin tener en cuenta qué  método  se  usó
              para iniciar el rastreo.  (direc is ignored.)

OBSERVACIONES

       Aunque los argumentos de ptrace se interpretan seg√ļn el prototipo dado,
       GNU libc declara actualmente ptrace como una función en la que sólo  el
       argumento  petici√n tiene sentido.  Esto significa que se pueden omitir
       los argumentos del final innecesarios, aunque al hacerlo  así  se  hace
       uso de comportamiento de gcc(1) sin documentar.

       init(8), el proceso con PID 1, no puede ser rastreado.

       La  disposición  de  los  contenidos  de  memoria  y  del área USER son
       bastante específicos del sistema operativo (y la arquitectura).

       El tama√Īo de una  "palabra"  viene  determinado  por  la  variante  del
       sistema operativo (por ejemplo, para un Linux de 32 bits es de 32 bits,
       etc.)

       El rastreo provoca unas pocas diferencias sutiles en  la  sem√°ntica  de
       los  procesos  rastreados.  Por  ejemplo,  si  se  ata  un  proceso con
       PTRACE_ATTACH, su padre original ya  no  puede  recibir  notificaciones
       mediante  wait  cuando  se detiene y no hay forma de que el nuevo padre
       pueda simular de forma efectiva esta notificación.

       Esta p√°gina documenta la forma en que funciona actualmente  la  llamada
       ptrace  en Linux. Su comportamiento difiere notablemente en otros Unix.
       En cualquier caso, el uso ptrace es altamente  específico  del  sistema
       operativo (y la arquitectura).

       La  p√°gina  de  manual de SunOS describe ptrace como "√ļnica y arcaica",
       que lo es. La interfaz de depuración basada en el sistema  de  ficheros
       virtual  "proc" presente en Solaris 2 implementa un superconjunto de la
       funcionalidad de ptrace de forma m√°s potente y uniforme.

VALOR DEVUELTO

       En caso de éxito,  las  peticiones  PTRACE_PEEK*  devuelven  los  datos
       solicitados,  mientras que las otras peticiones devuelven cero. En caso
       de error, todas las peticiones devuelven -1 y a errno(3) se  le  asigna
       un  valor  apropiado.  Ya  que  el  valor  devuelto  por  una  petición
       PTRACE_PEEK* con éxito puede ser -1, el invocador debe comprobar  errno
       después de tales peticiones para determinar si hubo error o no.

ERRORES

       EPERM  El  proceso indicado no puede ser rastreado. Esto podría deberse
              a que el padre no tiene suficientes  privilegios.  Los  procesos
              que  no  son  del  root no pueden rastrear procesos a los que no
              pueden enviar se√Īales o programas en ejecuci√≥n setuid/setgid por
              razones  obvias.  Alternativamente,  puede  que el proceso ya se
              esté rastreando o ser el proceso init (pid 1).

       ESRCH  El proceso especificado no existe o  el  invocador  no  lo  est√°
              rastreando  actualmente  o  no  est√° parado (para peticiones que
              necesiten que lo esté).

       EIO    Petici√n no es v√°lida o se ha intentado leer de  o  escribir  en
              una  √°rea  inv√°lida  de la memoria del padre o del hijo, o se ha
              producido una violación en la alineación  de  palabra  o  se  ha
              especificado   una   se√Īal  inv√°lida  durante  una  petici√≥n  de
              reinicio.

       EFAULT Se ha intentado leer de o escribir en una √°rea  inv√°lida  de  la
              memoria  del  padre  o del hijo, probablemente porque el √°rea no
              estaba asignada  o  no  era  accesible.  Desafortunadamente,  en
              Linux,  diferentes  versiones  de  este  fallo  devolver√°n EIO o
              EFAULT de forma m√°s o menos arbitraria.

CONFORME A

       SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3

V√ČASE TAMBI√ČN

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