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

NOMBRE

       ptrace - rastreo de un proceso

SINOPSIS

       #include <sys/ptrace.h>

       long  ptrace(enum  __ptrace_request  petici'on,  pid_t pid, void *direc,
       void *datos);

DESCRIPCI'ON

       La llamada al sistema ptrace proporciona un medio por el que un proceso
       padre  puede  observar  y  controlar  la  ejecucion  de  otro proceso y
       examinar  y  cambiar  su  imagen  de  memoria  y  registros.   Se   usa
       principalmente en la implementacion de depuracion 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 esta siendo rastreado, el hijo se detendra cada vez que reciba
       una senal, aun cuando la senal  se  haya  ignorado.  (La  excepcion  es
       SIGKILL  que  tiene  su efecto habitual.) El padre sera informado en su
       siguiente wait(2) y puede inspeccionar  y  modificar  el  proceso  hijo
       mientras esta parado.  A continuacion, el padre puede hacer que el hijo
       continue,  ignorando  opcionalmente  la  senal  recibida   (o   incluso
       entregando una senal distinta en su lugar).  Cuando el padre termina de
       rastrear, puede terminar el hijo con PTRACE_KILL o hace que se continue
       ejecutando en un modo normal sin rastreo mediante PTRACE_DETACH.

       El valor del argumento petici'on determina la accion a realizar:

       PTRACE_TRACEME
              Indica  que  este  proceso  va  a  ser  rastreado  por su padre.
              Cualquier senal (excepto SIGKILL) entregada a este proceso  hara
              que  se  pare y su padre sera informado mediante wait.  Tambien,
              cualquier llamada posterior a exec realizada  por  este  proceso
              hara  que  se le envie un SIGTRAP, dando al padre la posibilidad
              de obtener el control antes de que el nuevo programa comience su
              ejecucion.  Probablemente,  un  proceso  no  deberia  hacer esta
              peticion si su padre no esta esperando para  rastrearlo.   (pid,
              direc y datos se ignoran.)

       La peticion anterior la usa solo el proceso hijo. El resto las usa solo
       el padre. En las siguientes peticiones,  pid  indica  el  proceso  hijo
       sobre  el  que se actuara. Para peticiones distintas de PTRACE_KILL, el
       proceso hijo debe estar parado.

       PTRACE_PEEKTEXT, PTRACE_PEEKDATA
              Lee una palabra de la posicion direc.

       PTRACE_PEEKUSER
              Lee una palabra en el desplazamiento direc  del  area  USER  del
              hijo,  que  contiene  los  registros y otra informacion sobre el
              proceso (vea  <linux/user.h>  y  <sys/user.h>).  La  palabra  se
              devuelve  como  resultado de la llamada ptrace.  Tipicamente, el
              desplazamiento debe esta alineado en una  frontera  de  palabra,
              aunque  esto  podria  variar  en  cada  arquitectura.  (datos se
              ignora).

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

       PTRACE_POKEUSER
              Copia una palabra de la posicion datos al  desplazamiento  direc
              en  el area USER del hijo. Al igual que antes, el desplazamiento
              debe estar tipicamente alineado en una frontera de palabra. Para
              conservar  la  integridad  del nucleo, algunas modificaciones al
              area USER se encuentran deshabilitadas.

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

       PTRACE_SETREGS, PTRACE_SETFPREGS
              Copia los registros de proposito general o de punto flotante del
              hijo, respectivamente, desde la posicion  datos  del  padre.  Al
              igual  que  para  PTRACE_POKEUSER,  alguna modificaciones de los
              registros de  proposito  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 senal que se entregara  al  hijo.
              En  otro caso, no se entrega ninguna senal. Asi, por ejemplo, el
              padre puede controlar si una senal 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 ejecucion de una unica
              intruccion, respectivamente. (Como es usual, el hijo tambien  se
              detendra  al recibir una senal). Desde la perspectiva del padre,
              el hijo aparecera como si se hubiera  detenido  al  recibir  una
              senal  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 continuacion otra PTRACE_SYSCALL e
              inspeccionar los valores devueltos por  la  llamada  al  sistema
              cuando se detenga la segunda vez. (direc se ignora.)

       PTRACE_KILL
              Envia al hijo una senal SIGKILL para que termine. (direc y datos
              se ignoran.)

       PTRACE_ATTACH
              Ata al proceso especificado en pid, convirtiendolo 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  mayoria  de propositos (por
              ejemplo,  recibira  notificacion  de  los  eventos  del  hijo  y
              aparecera  en  la  salida de ps(1) como padre del hijo), pero un
              getppid(2) por parte del hijo todavia devolvera el pid del padre
              original.  Al  hijo se le envia un SIGSTOP pero, necesariamente,
              no tiene  por  que  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 quizas no
              sea  intencionado,  bajo  Linux  un  proceso rastreado puede ser
              desatado de esta manera sin tener en cuenta que  metodo  se  uso
              para iniciar el rastreo.  (direc is ignored.)

OBSERVACIONES

       Aunque los argumentos de ptrace se interpretan segun el prototipo dado,
       GNU libc declara actualmente ptrace como una funcion en la que solo  el
       argumento  petici'on tiene sentido.  Esto significa que se pueden omitir
       los argumentos del final innecesarios, aunque al hacerlo  asi  se  hace
       uso de comportamiento de gcc(1) sin documentar.

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

       La  disposicion  de  los  contenidos  de  memoria  y  del area USER son
       bastante especificos del sistema operativo (y la arquitectura).

       El tamano 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  semantica  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 notificacion.

       Esta pagina 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  especifico  del  sistema
       operativo (y la arquitectura).

       La  pagina  de  manual de SunOS describe ptrace como "unica y arcaica",
       que lo es. La interfaz de depuracion basada en el sistema  de  ficheros
       virtual  "proc" presente en Solaris 2 implementa un superconjunto de la
       funcionalidad de ptrace de forma mas potente y uniforme.

VALOR DEVUELTO

       En caso de exito,  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  peticion
       PTRACE_PEEK* con exito puede ser -1, el invocador debe comprobar  errno
       despues de tales peticiones para determinar si hubo error o no.

ERRORES

       EPERM  El  proceso indicado no puede ser rastreado. Esto podria 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 senales o programas en ejecucion setuid/setgid por
              razones  obvias.  Alternativamente,  puede  que el proceso ya se
              este rastreando o ser el proceso init (pid 1).

       ESRCH  El proceso especificado no existe o  el  invocador  no  lo  esta
              rastreando  actualmente  o  no  esta parado (para peticiones que
              necesiten que lo este).

       EIO    Petici'on no es valida o se ha intentado leer de  o  escribir  en
              una  area  invalida  de la memoria del padre o del hijo, o se ha
              producido una violacion en la alineacion  de  palabra  o  se  ha
              especificado   una   senal  invalida  durante  una  peticion  de
              reinicio.

       EFAULT Se ha intentado leer de o escribir en una area  invalida  de  la
              memoria  del  padre  o del hijo, probablemente porque el area no
              estaba asignada  o  no  era  accesible.  Desafortunadamente,  en
              Linux,  diferentes  versiones  de  este  fallo  devolveran EIO o
              EFAULT de forma mas o menos arbitraria.

CONFORME A

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

V'EASE TAMBI'EN

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