Return to ptrace.2 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man2

Annotation of cci/usr/src/man/man2/ptrace.2, revision 1.1

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

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