Print this page
8158 Want named threads API
9857 proc manpages should have LIBRARY section
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3proc/Pgrab_core.3proc
+++ new/usr/src/man/man3proc/Pgrab_core.3proc
1 1 .\"
2 2 .\" This file and its contents are supplied under the terms of the
3 3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 4 .\" You may only use this file in accordance with the terms of version
5 5 .\" 1.0 of the CDDL.
6 6 .\"
7 7 .\" A full copy of the text of the CDDL should have accompanied this
8 8 .\" source. A copy of the CDDL is also available via the Internet at
9 9 .\" http://www.illumos.org/license/CDDL.
10 10 .\"
|
↓ open down ↓ |
10 lines elided |
↑ open up ↑ |
11 11 .\"
12 12 .\" Copyright 2015 Joyent, Inc.
13 13 .\"
14 14 .Dd May 11, 2016
15 15 .Dt PGRAB_CORE 3PROC
16 16 .Os
17 17 .Sh NAME
18 18 .Nm Pgrab_core ,
19 19 .Nm Pfgrab_core
20 20 .Nd grab a core file
21 -.Sh SYNOPSIS
21 +.Sh LIBRARY
22 22 .Lb libproc
23 +.Sh SYNOPSIS
23 24 .In libproc.h
24 25 .Ft "struct ps_prochandle *"
25 26 .Fo Pgrab_core
26 27 .Fa "const char *core"
27 28 .Fa "const char *aout"
28 29 .Fa "int gflag"
29 30 .Fa "int *perr"
30 31 .Fc
31 32 .Ft "struct ps_prochandle *"
32 33 .Fo Pfgrab_core
33 34 .Fa "int core_fd"
34 35 .Fa "const char *aout"
35 36 .Fa "int *perr"
36 37 .Fc
37 38 .Sh DESCRIPTION
38 39 The
39 40 .Fn Pgrab_core
40 41 and
41 42 .Fn Pfgrab_core
42 43 functions open a core file for introspection.
43 44 Unlike live processes, core files cannot have their state modified;
44 45 however, all of the functions that iterate or query state will work.
45 46 These functions work on all illumos core files and the core files of some other
46 47 operating systems.
47 48 See both
48 49 .Xr core 4
49 50 and the
50 51 .Em Core Files
51 52 section of
52 53 .Xr libproc 3LIB
53 54 for more information.
54 55 .Pp
55 56 The
56 57 .Fn Pgrab_core
57 58 function attempts to open the core file specified by
58 59 .Fa core .
59 60 The system attempts to determine the path of the original executable.
60 61 The argument
61 62 .Fa aout
62 63 may either be the path to that file, a path to a directory to search, or the
63 64 .Dv NULL
64 65 pointer, if neither is known.
65 66 The system will search for it and will supplement information in the core file
66 67 with that.
67 68 .Pp
68 69 The
69 70 .Fa gflag
70 71 argument to the
71 72 .Fn Pgrab_core
72 73 function controls how the file is opened.
73 74 If the
74 75 .Dv PGRAB_RDONLY
75 76 flag is specified, then the core file will be opened with the
76 77 .Xr open 2
77 78 flag
78 79 .Dv O_RDONLY .
79 80 Otherwise, it will be opened
80 81 .Dv O_RDWR .
81 82 .Pp
82 83 The
83 84 .Fa perr
84 85 argument must be a
85 86 .Pf non- Dv NULL
86 87 pointer which will store a more detailed error in the event that the
87 88 .Fn Pgrab_core
88 89 function fails.
89 90 A human-readable form of the error can be obtained through the routine
90 91 .Xr Pgrab_error 3PROC .
91 92 .Pp
92 93 The
93 94 .Fn Pfgrab_core
94 95 is similar to the
95 96 .Fn Pgrab_core
96 97 function.
97 98 Except, instead of operating on a path, it opens a handle to the core file
98 99 referenced by
99 100 .Fa core_fd .
100 101 The
101 102 .Fa aout
102 103 and
103 104 .Fa perr
104 105 arguments are identical to those in the
105 106 .Fn Pgrab_core
106 107 function.
107 108 .Pp
108 109 The handle returned, from either function, is valid until it is closed
109 110 with
110 111 .Xr Prelease 3PROC
111 112 or
112 113 .Xr Pfree 3PROC .
113 114 .Sh RETURN VALUES
114 115 Upon successful completion, the
115 116 .Fn Pgrab_core
116 117 and
117 118 .Fn Pfgrab_core
118 119 functions return a
119 120 .Sy libproc
120 121 handle to the core file.
121 122 Otherwise,
122 123 .Dv NULL
123 124 is returned and
124 125 .Fa perr
125 126 is filled in with a more detailed error message.
126 127 .Sh ERRORS
127 128 The
128 129 .Fn Pgrab_core
129 130 function will fail if:
130 131 .Bl -tag -width Er
131 132 .It Er G_NOCORE
132 133 The file
133 134 .Fa core
134 135 does not exist.
135 136 .It Er G_STRANGE
136 137 An unexpected system error occurred while trying to open
137 138 .Fa core .
138 139 The value of
139 140 .Sy errno
140 141 indicates the system failure.
141 142 .El
142 143 .Pp
143 144 The
144 145 .Fn Pgrab_core
145 146 and
146 147 .Fn Pfgrab_core
147 148 functions will fail if:
148 149 .Bl -tag -width Er
149 150 .It Dv G_ELF
150 151 An unexpected
151 152 .Xr libelf 3LIB
152 153 failure occurred.
153 154 .It Dv G_FORMAT
154 155 The core file referred to by either
155 156 .Fa core
156 157 or
157 158 .Fa core_fd
158 159 is not a valid ELF core file.
159 160 .It Dv G_ISAINVAL
160 161 The architecture of the core file referred to by either
161 162 .Fa core
162 163 or
163 164 .Fa core_fd
164 165 does not match the current running system.
165 166 .It Dv G_LP64
166 167 The calling process is a 32-bit process and the core file referenced by
167 168 either
168 169 .Fa core
169 170 or
170 171 .Fa core_fd
171 172 refers to a 64-bit process.
172 173 .It Dv G_NOTE
173 174 The ELF notes present in the core file referred to by either
174 175 .Fa core
175 176 or
176 177 .Fa core_fd
177 178 are corrupt or missing required data.
178 179 .It Dv G_STRANGE
179 180 An unanticipated system error occurred while trying to open the core
180 181 file and create the handle.
181 182 The value of
182 183 .Sy errno
183 184 indicates the system failure.
184 185 .El
185 186 .Sh INTERFACE STABILITY
186 187 .Sy Uncommitted
187 188 .Sh MT-LEVEL
188 189 .Sy MT-Safe
189 190 .Sh SEE ALSO
190 191 .Xr gcore 1 ,
191 192 .Xr open 2 ,
192 193 .Xr errno 3C ,
193 194 .Xr libproc 3LIB ,
194 195 .Xr Pfree 3PROC ,
195 196 .Xr Pgrab_error 3PROC ,
196 197 .Xr Prelease 3PROC ,
197 198 .Xr core 4
|
↓ open down ↓ |
165 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX