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 LIBRARY
  21 .Lb libproc
  22 .Sh SYNOPSIS
  23 .In libproc.h
  24 .Ft int
  25 .Fo Psetbkpt
  26 .Fa "struct ps_prochandle *P"
  27 .Fa "uintptr_t address"
  28 .Fa "ulong_t *saved"
  29 .Fc
  30 .Sh DESCRIPTION
  31 The
  32 .Fn Psetbkpt
  33 function sets a breakpoint instruction at the address
  34 .Fa address
  35 in the process handle
  36 .Fa P .
  37 The instruction that used to be set will be set in
  38 .Fa saved
  39 and should be retained.
  40 .Pp
  41 A breakpoint will remain in place until a subsequent call to
  42 .Xr Pdelbkpt 3PROC .
  43 The value stored in
  44 .Fa saved
  45 should be passed as the third argument to
  46 .Xr Pdelbkpt 3PROC .
  47 .Pp
  48 When a process executes an instruction that has been replaced with a
  49 breakpoint it generates a
  50 .Sy FLTBPT
  51 trap
  52 causing the thread to stop.
  53 .Pp
  54 Note, breakpoints may only be set in active processes.
  55 They may not be set in process handles that refer to core files, zombie
  56 processes, or files.
  57 .Sh RETURN VALUES
  58 Upon successful completion, the
  59 .Fn Psetbkpt
  60 function sets the breakpoint and
  61 returns
  62 .Sy 0 .
  63 Otherwise,
  64 .Sy -1
  65 is returned and
  66 .Sy errno
  67 is set to indicate the error.
  68 .Sh ERRORS
  69 For a full list of possible errors see the
  70 .Sy DIAGNOSTICS
  71 section in
  72 .Xr proc 4 .
  73 .Pp
  74 The
  75 .Fn Psetbkpt
  76 function will fail if:
  77 .Bl -tag -width Er
  78 .It Er ENOENT
  79 .Fa P
  80 does not refer to an active process.
  81 .It Er EBUSY
  82 A breakpoint instruction was already written by another debugger.
  83 .El
  84 .Sh INTERFACE STABILITY
  85 .Sy Uncommitted
  86 .Sh MT-LEVEL
  87 See
  88 .Sy LOCKING
  89 in
  90 .Xr libproc 3LIB .
  91 .Sh SEE ALSO
  92 .Xr libproc 3LIB ,
  93 .Xr Pdelbkpt 3PROC ,
  94 .Xr proc 4