Return to ptrace.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys

Annotation of 43BSDReno/lib/libc/sys/ptrace.2, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1980 Regents of the University of California.
        !             2: .\" All rights reserved.  The Berkeley software License Agreement
        !             3: .\" specifies the terms and conditions for redistribution.
        !             4: .\"
        !             5: .\"    @(#)ptrace.2    6.4 (Berkeley) 5/23/86
        !             6: .\"
        !             7: .TH PTRACE 2 "May 23, 1986"
        !             8: .UC 4
        !             9: .SH NAME
        !            10: ptrace \- process trace
        !            11: .SH SYNOPSIS
        !            12: .nf
        !            13: .ft B
        !            14: #include <sys/signal.h>
        !            15: #include <sys/ptrace.h>
        !            16: .PP
        !            17: .ft B
        !            18: ptrace(request, pid, addr, data)
        !            19: int request, pid, *addr, data;
        !            20: .fi
        !            21: .SH DESCRIPTION
        !            22: .I Ptrace
        !            23: provides a means by which a parent process
        !            24: may control the execution of a child process,
        !            25: and examine and change its core image.
        !            26: Its primary use is for the implementation of breakpoint debugging.
        !            27: There are four arguments whose interpretation
        !            28: depends on a
        !            29: .I request
        !            30: argument.
        !            31: Generally,
        !            32: .I pid
        !            33: is the process ID of the traced process,
        !            34: which must be a child (no more distant descendant)
        !            35: of the tracing process.
        !            36: A process being traced
        !            37: behaves normally until it encounters some signal
        !            38: whether internally generated
        !            39: like \*(lqillegal instruction\*(rq or externally
        !            40: generated like \*(lqinterrupt\*(rq.
        !            41: See
        !            42: .IR sigvec (2)
        !            43: for the list.
        !            44: Then the traced process enters a stopped state
        !            45: and its parent is notified via
        !            46: .IR  wait (2).
        !            47: When the child is in the stopped state,
        !            48: its core image can be examined and modified
        !            49: using
        !            50: .IR ptrace .
        !            51: If desired, another
        !            52: .I ptrace
        !            53: request can then cause the child either to terminate
        !            54: or to continue, possibly ignoring the signal.
        !            55: .PP
        !            56: The value of the
        !            57: .I request
        !            58: argument determines the precise
        !            59: action of the call:
        !            60: .TP 4
        !            61: PT_TRACE_ME
        !            62: This request is the only one used by the child process;
        !            63: it declares that the process is to be traced by its parent.
        !            64: All the other arguments are ignored.
        !            65: Peculiar results will ensue
        !            66: if the parent does not expect to trace the child.
        !            67: .TP 4
        !            68: PT_READ_I, PT_READ_D
        !            69: The
        !            70: word in the child process's address space
        !            71: at
        !            72: .I addr
        !            73: is returned.
        !            74: If I and D space are separated (e.g. historically
        !            75: on a pdp-11), request PT_READ_I indicates I space,
        !            76: PT_READ_D D space.
        !            77: .I Addr
        !            78: must be even on some machines.
        !            79: The child must be stopped.
        !            80: The input
        !            81: .I data
        !            82: is ignored.
        !            83: .TP 4
        !            84: PT_READ_U
        !            85: The word
        !            86: of the system's per-process data area corresponding to
        !            87: .I addr
        !            88: is returned.
        !            89: .I Addr
        !            90: must be even on some machines and less than 512.
        !            91: This space contains the registers and other information about
        !            92: the process;
        !            93: its layout corresponds to the
        !            94: .I user
        !            95: structure in the system.
        !            96: .TP 4
        !            97: PT_WRITE_I, PT_WRITE_D
        !            98: The
        !            99: given
        !           100: .I data
        !           101: is written at the word in the process's address space corresponding to
        !           102: .I addr,
        !           103: which must be even on some machines.
        !           104: No useful value is returned.
        !           105: If I and D space are separated, request PT_WRITE_I indicates I space, 
        !           106: PT_WRITE_D D space.
        !           107: Attempts to write in pure procedure
        !           108: fail if another process is executing the same file.
        !           109: .TP 4
        !           110: PT_WRITE_U
        !           111: The process's system data is written,
        !           112: as it is read with request PT_READ_U.
        !           113: Only a few locations can be written in this way:
        !           114: the general registers,
        !           115: the floating point status and registers,
        !           116: and certain bits of the processor status word.
        !           117: .TP 4
        !           118: PT_CONTINUE
        !           119: The
        !           120: .I data
        !           121: argument is taken as a signal number
        !           122: and the child's execution continues
        !           123: at location
        !           124: .I addr
        !           125: as if it had incurred that signal.
        !           126: Normally the signal number will be
        !           127: either 0 to indicate that the signal that caused the stop
        !           128: should be ignored,
        !           129: or that value fetched out of the
        !           130: process's image indicating which signal caused
        !           131: the stop.
        !           132: If
        !           133: .I addr
        !           134: is (int *)1 then execution continues from where it stopped.
        !           135: .TP 4
        !           136: PT_KILL
        !           137: The traced process terminates.
        !           138: .TP 4
        !           139: PT_STEP
        !           140: Execution continues as in request PT_CONTINUE;
        !           141: however, as soon as possible after execution of at least one instruction,
        !           142: execution stops again.
        !           143: The signal number from the stop is
        !           144: SIGTRAP.
        !           145: (On the VAX-11 the T-bit is used and just one instruction
        !           146: is executed.)
        !           147: This is part of the mechanism for implementing breakpoints.
        !           148: .PP
        !           149: As indicated,
        !           150: these calls
        !           151: (except for request PT_TRACE_ME)
        !           152: can be used only when the subject process has stopped.
        !           153: The
        !           154: .I wait
        !           155: call is used to determine
        !           156: when a process stops;
        !           157: in such a case the \*(lqtermination\*(rq status
        !           158: returned by
        !           159: .I wait
        !           160: has the value 0177 to indicate stoppage rather
        !           161: than genuine termination.
        !           162: .PP
        !           163: To forestall possible fraud,
        !           164: .I ptrace
        !           165: inhibits the set-user-id and set-group-id facilities
        !           166: on subsequent
        !           167: .IR  execve (2)
        !           168: calls.
        !           169: If a traced process calls
        !           170: .IR execve ,
        !           171: it will stop before executing the first instruction of the new image
        !           172: showing signal SIGTRAP.
        !           173: .PP
        !           174: On a VAX-11, \*(lqword\*(rq also means a 32-bit integer,
        !           175: but the \*(lqeven\*(rq
        !           176: restriction does not apply.
        !           177: .SH "RETURN VALUE
        !           178: A 0 value is returned if the call succeeds.  If the call fails
        !           179: then a \-1 is returned and the global variable \fIerrno\fP is
        !           180: set to indicate the error.
        !           181: .SH "ERRORS
        !           182: .TP 15
        !           183: [EIO]
        !           184: The request code is invalid.
        !           185: .TP 15
        !           186: [ESRCH]
        !           187: The specified process does not exist.
        !           188: .TP 15
        !           189: [EIO]
        !           190: The given signal number is invalid.
        !           191: .TP 15
        !           192: [EIO]
        !           193: The specified address is out of bounds.
        !           194: .TP 15
        !           195: [EPERM]
        !           196: The specified process cannot be traced.
        !           197: .SH "SEE ALSO"
        !           198: wait(2), sigvec(2), adb(1)
        !           199: .SH BUGS
        !           200: .I Ptrace
        !           201: is unique and arcane; it should be replaced with a special file that
        !           202: can be opened and read and written.  The control functions could then
        !           203: be implemented with
        !           204: .IR ioctl (2)
        !           205: calls on this file.  This would be simpler to understand and have much
        !           206: higher performance.
        !           207: .PP
        !           208: The request PT_TRACE_ME call should be able to specify
        !           209: signals that are to be treated normally and not cause a stop.
        !           210: In this way, for example,
        !           211: programs with simulated floating point (which
        !           212: use \*(lqillegal instruction\*(rq signals at a very high rate)
        !           213: could be efficiently debugged.
        !           214: .PP
        !           215: The error indication, \-1, is a legitimate function value;
        !           216: .I errno,
        !           217: (see
        !           218: .IR intro (2)),
        !           219: can be used to disambiguate.
        !           220: .PP
        !           221: It should be possible to stop a process on occurrence of a system
        !           222: call;
        !           223: in this way a completely controlled environment could
        !           224: be provided.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.