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