usr/src/man/man3proc/Psetbkpt.3proc

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2015 Joyent, Inc.
  13 .\"
  14 .Dd May 11, 2016
  15 .Dt PSETBKPT 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Psetbkpt
  19 .Nd set a breakpoint trap in a process
  20 .Sh SYNOPSIS
  21 .Lb libproc
  22 .In libproc.h
  23 .Ft int
  24 .Fo Psetbkpt
  25 .Fa "struct ps_prochandle *P"
  26 .Fa "uintptr_t address"
  27 .Fa "ulong_t *saved"
  28 .Fc
  29 .Sh DESCRIPTION
  30 The
  31 .Fn Psetbkpt
  32 function sets a breakpoint instruction at the address
  33 .Fa address
  34 in the process handle
  35 .Fa P .
  36 The instruction that used to be set will be set in
  37 .Fa saved
  38 and should be retained.
  39 .Pp
  40 A breakpoint will remain in place until a subsequent call to
  41 .Xr Pdelbkpt 3PROC .
  42 The value stored in
  43 .Fa saved
  44 should be passed as the third argument to
  45 .Xr Pdelbkpt 3PROC .
  46 .Pp
  47 When a process executes an instruction that has been replaced with a
  48 breakpoint it generates a
  49 .Sy FLTBPT
  50 trap
  51 causing the thread to stop.
  52 .Pp
  53 Note, breakpoints may only be set in active processes. They may not be
  54 set in process handles that refer to core files, zombie processes, or
  55 files.
  56 .Sh RETURN VALUES
  57 Upon successful completion, the
  58 .Fn Psetbkpt
  59 function sets the breakpoint and
  60 returns
  61 .Sy 0 .
  62 Otherwise,
  63 .Sy -1
  64 is returned and
  65 .Sy errno
  66 is set to indicate the error.
  67 .Sh ERRORS
  68 For a full list of possible errors see the
  69 .Sy DIAGNOSTICS
  70 section in
  71 .Xr proc 4 .
  72 .Pp
  73 The
  74 .Fn Psetbkpt
  75 function will fail if:
  76 .Bl -tag -width Er
  77 .It Er ENOENT
  78 .Fa P
  79 does not refer to an active process.
  80 .It Er EBUSY
  81 A breakpoint instruction was already written by another debugger.
  82 .El
  83 .Sh INTERFACE STABILITY
  84 .Sy Uncommitted
  85 .Sh MT-LEVEL
  86 See
  87 .Sy LOCKING
  88 in
  89 .Xr libproc 3LIB .
  90 .Sh SEE ALSO
  91 .Xr libproc 3LIB ,
  92 .Xr Pdelbkpt 3PROC ,
  93 .Xr proc 4