base-ij-webrev Sdiff usr/src/man/man3lib/libproc.3lib

Print this page

15254 %ymm registers not restored after signal handler
15367 x86 getfpregs() summons corrupting %xmm ghosts
15333 want x86 /proc xregs support (libc_db, libproc, mdb, etc.)
15336 want libc functions for extended ucontext_t
15334 want ps_lwphandle-specific reg routines
15328 FPU_CW_INIT mistreats reserved bit
15335 i86pc fpu_subr.c isn't really platform-specific
15332 setcontext(2) isn't actually noreturn
15331 need <sys/stdalign.h>
Change-Id: I7060aa86042dfb989f77fc3323c065ea2eafa9ad
Conflicts:
    usr/src/uts/common/fs/proc/prcontrol.c
    usr/src/uts/intel/os/archdep.c
    usr/src/uts/intel/sys/ucontext.h
    usr/src/uts/intel/syscall/getcontext.c

   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 2018 Joyent, Inc.
  13 .\" Copyright (c) 2019 Carlos Neira <cneirabustos@gmail.com>
  14 .\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.

  15 .\"
  16 .Dd March 10, 2023
  17 .Dt LIBPROC 3LIB
  18 .Os
  19 .Sh NAME
  20 .Nm libproc
  21 .Nd process control library
  22 .Sh SYNOPSIS
  23 .Lb libproc
  24 .In libproc.h
  25 .Sh DESCRIPTION
  26 The
  27 .Nm
  28 library provides consumers a general series of interfaces to inspect
  29 and control both live processes and core files.
  30 It is intended for introspection tools such as debuggers by providing a
  31 high-level interface to the /proc file system
  32 .Pf ( Xr proc 5 ) .
  33 .Pp
  34 The
  35 .Nm
  36 library provides interfaces that focus on:

 201 .It Sy Preopen Ta Sy Pxcreate
 202 .El
 203 .Ss Process interrogation and manipulation
 204 The following routines obtain information about a process and allow
 205 manipulation of the process itself.
 206 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 207 .It Sy Paddr_to_ctf Ta Sy Paddr_to_loadobj
 208 .It Sy Paddr_to_map Ta Sy Paddr_to_text_map
 209 .It Sy Pasfd Ta Sy Pclearfault
 210 .It Sy Pclearsig Ta Sy Pcontent
 211 .It Sy Pcred Ta Sy Pctlfd
 212 .It Sy Pdelbkpt Ta Sy Pdelwapt
 213 .It Sy Pdstop Ta Sy Pexecname
 214 .It Sy Pfault Ta Sy Pfgcore
 215 .It Sy Pgcore Ta Sy Pgetareg
 216 .It Sy Pgetauxval Ta Sy Pgetauxvec
 217 .It Sy Pgetenv Ta Sy Pisprocdir
 218 .It Sy Pissyscall_prev Ta Sy Plmid
 219 .It Sy Plmid_to_loadobj Ta Sy Plmid_to_map
 220 .It Sy Plookup_by_addr Ta Sy Plookup_by_name
 221 .It Sy Plwp_alt_stack Ta Sy Plwp_getfpregs
 222 .It Sy Plwp_getname Ta Sy Plwp_getpsinfo
 223 .It Sy Plwp_getregs Ta Sy Plwp_getspymaster
 224 .It Sy Plwp_main_stack Ta Sy Plwp_setfpregs
 225 .It Sy Plwp_setregs Ta Sy Plwp_stack
 226 .It Sy Pname_to_ctf Ta Sy Pname_to_loadobj
 227 .It Sy Pname_to_map Ta Sy Pobjname
 228 .It Sy Pobjname_resolved Ta Sy Pplatform
 229 .It Sy Ppltdest Ta Sy Ppriv
 230 .It Sy Ppsinfo Ta Sy Pputareg
 231 .It Sy Prd_agent Ta Sy Pread
 232 .It Sy Pread_string Ta Sy Preset_maps
 233 .It Sy Psetbkpt Ta Sy Psecflags
 234 .It Sy Psetcred Ta Sy Psetfault
 235 .It Sy Psetflags Ta Sy Psetpriv
 236 .It Sy Psetrun Ta Sy Psetsignal
 237 .It Sy Psetsysentry Ta Sy Psetsysexit
 238 .It Sy Psetwapt Ta Sy Psetzoneid
 239 .It Sy Psignal Ta Sy Pstate
 240 .It Sy Pstatus Ta Sy Pstop
 241 .It Sy Pstopstatus Ta Sy Psync
 242 .It Sy Psysentry Ta Sy Psysexit
 243 .It Sy Puname Ta Sy Pupanic
 244 .It Sy Pupanic_free Ta Sy Punsetflags
 245 .It Sy Pupdate_maps Ta Sy Pupdate_syms
 246 .It Sy Pwait Ta Sy Pwrite
 247 .It Sy Pxecbkpt Ta Sy Pxecwapt
 248 .It Sy Pxlookup_by_addr Ta Sy Pxlookup_by_addr_resolved
 249 .It Sy Pxlookup_by_name Ta Sy Pzonename
 250 .It Sy Pzonepath Ta Sy Pzoneroot Ta
 251 .El
 252 .Ss Thread interrogation and manipulation
 253 The following routines obtain information about a thread and allow
 254 manipulation of the thread itself.
 255 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 256 .It Sy Lalt_stack Ta Sy Lclearfault
 257 .It Sy Lclearsig Ta Sy Lctlfd
 258 .It Sy Ldstop Ta Sy Lgetareg
 259 .It Sy Lmain_stack Ta Sy Lprochandle
 260 .It Sy Lpsinfo Ta Sy Lputareg
 261 .It Sy Lsetrun Ta Sy Lstack



 262 .It Sy Lstate Ta Sy Lstatus
 263 .It Sy Lstop Ta Sy Lsync
 264 .It Sy Lwait Ta Sy Lxecbkpt
 265 .It Sy Lxecwapt Ta ""
 266 .El









 267 .Ss System Call Injection
 268 The following routines are used to inject specific system calls and have
 269 them run in the context of a process.
 270 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 271 .It Sy pr_access Ta Sy pr_close
 272 .It Sy pr_creat Ta Sy pr_door_info
 273 .It Sy pr_exit Ta Sy pr_fcntl
 274 .It Sy pr_fstat Ta Sy pr_fstat64
 275 .It Sy pr_fstatvfs Ta Sy pr_getitimer
 276 .It Sy pr_getpeername Ta Sy pr_getpeerucred
 277 .It Sy pr_getprojid Ta Sy pr_getrctl
 278 .It Sy pr_getrlimit Ta Sy pr_getrlimit64
 279 .It Sy pr_getsockname Ta Sy pr_getsockopt
 280 .It Sy pr_gettaskid Ta Sy pr_getzoneid
 281 .It Sy pr_ioctl Ta Sy pr_link
 282 .It Sy pr_llseek Ta Sy pr_lseek
 283 .It Sy pr_lstat Ta Sy pr_lstat64
 284 .It Sy pr_memcntl Ta Sy pr_meminfo
 285 .It Sy pr_mmap Ta Sy pr_munmap
 286 .It Sy pr_open Ta Sy pr_processor_bind

 321 .It Sy proc_str2content Ta Sy proc_str2flt
 322 .It Sy proc_str2fltset Ta Sy proc_str2sig
 323 .It Sy proc_str2sigset Ta Sy proc_str2sys
 324 .It Sy proc_str2sysset Ta Sy proc_sysname
 325 .It Sy proc_sysset2str Ta Sy proc_unctrl_psinfo
 326 .El
 327 .Ss x86 Specific Routines
 328 The following routines are specific to the x86, 32-bit and 64-bit,
 329 versions of the
 330 .Nm
 331 library.
 332 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 333 .It Sy Pldt Ta Sy proc_get_ldt
 334 .El
 335 .Ss SPARC specific Routines
 336 The following functions are specific to the SPARC, 32-bit and 64-bit,
 337 versions of the
 338 .Nm
 339 library.
 340 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 341 .It Sy Plwp_getgwindows Ta Sy Plwp_getxregs
 342 .It Sy Plwp_setxregs Ta Sy ""
 343 .El
 344 .Pp
 345 The following functions are specific to the 64-bit SPARC version of the
 346 .Nm
 347 library.
 348 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 349 .It Sy Plwp_getasrs Ta Sy Plwp_setasrs
 350 .El
 351 .Sh PROCESS STATES
 352 Every process handle that exists in
 353 .Nm
 354 has a state.
 355 In some cases, such as for core files, these states are static.
 356 In other cases, such as handles that correspond to a running process or a
 357 created process, these states are dynamic and change based on actions taken in
 358 the library.
 359 The state can be obtained with the
 360 .Xr Pstate 3PROC
 361 function.
 362 .Pp

   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 2018 Joyent, Inc.
  13 .\" Copyright (c) 2019 Carlos Neira <cneirabustos@gmail.com>
  14 .\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
  15 .\" Copyright 2023 Oxide Computer Company
  16 .\"
  17 .Dd March 20, 2023
  18 .Dt LIBPROC 3LIB
  19 .Os
  20 .Sh NAME
  21 .Nm libproc
  22 .Nd process control library
  23 .Sh SYNOPSIS
  24 .Lb libproc
  25 .In libproc.h
  26 .Sh DESCRIPTION
  27 The
  28 .Nm
  29 library provides consumers a general series of interfaces to inspect
  30 and control both live processes and core files.
  31 It is intended for introspection tools such as debuggers by providing a
  32 high-level interface to the /proc file system
  33 .Pf ( Xr proc 5 ) .
  34 .Pp
  35 The
  36 .Nm
  37 library provides interfaces that focus on:

 202 .It Sy Preopen Ta Sy Pxcreate
 203 .El
 204 .Ss Process interrogation and manipulation
 205 The following routines obtain information about a process and allow
 206 manipulation of the process itself.
 207 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 208 .It Sy Paddr_to_ctf Ta Sy Paddr_to_loadobj
 209 .It Sy Paddr_to_map Ta Sy Paddr_to_text_map
 210 .It Sy Pasfd Ta Sy Pclearfault
 211 .It Sy Pclearsig Ta Sy Pcontent
 212 .It Sy Pcred Ta Sy Pctlfd
 213 .It Sy Pdelbkpt Ta Sy Pdelwapt
 214 .It Sy Pdstop Ta Sy Pexecname
 215 .It Sy Pfault Ta Sy Pfgcore
 216 .It Sy Pgcore Ta Sy Pgetareg
 217 .It Sy Pgetauxval Ta Sy Pgetauxvec
 218 .It Sy Pgetenv Ta Sy Pisprocdir
 219 .It Sy Pissyscall_prev Ta Sy Plmid
 220 .It Sy Plmid_to_loadobj Ta Sy Plmid_to_map
 221 .It Sy Plookup_by_addr Ta Sy Plookup_by_name





 222 .It Sy Pname_to_ctf Ta Sy Pname_to_loadobj
 223 .It Sy Pname_to_map Ta Sy Pobjname
 224 .It Sy Pobjname_resolved Ta Sy Pplatform
 225 .It Sy Ppltdest Ta Sy Ppriv
 226 .It Sy Ppsinfo Ta Sy Pputareg
 227 .It Sy Prd_agent Ta Sy Pread
 228 .It Sy Pread_string Ta Sy Preset_maps
 229 .It Sy Psetbkpt Ta Sy Psecflags
 230 .It Sy Psetcred Ta Sy Psetfault
 231 .It Sy Psetflags Ta Sy Psetpriv
 232 .It Sy Psetrun Ta Sy Psetsignal
 233 .It Sy Psetsysentry Ta Sy Psetsysexit
 234 .It Sy Psetwapt Ta Sy Psetzoneid
 235 .It Sy Psignal Ta Sy Pstate
 236 .It Sy Pstatus Ta Sy Pstop
 237 .It Sy Pstopstatus Ta Sy Psync
 238 .It Sy Psysentry Ta Sy Psysexit
 239 .It Sy Puname Ta Sy Pupanic
 240 .It Sy Pupanic_free Ta Sy Punsetflags
 241 .It Sy Pupdate_maps Ta Sy Pupdate_syms
 242 .It Sy Pwait Ta Sy Pwrite
 243 .It Sy Pxecbkpt Ta Sy Pxecwapt
 244 .It Sy Pxlookup_by_addr Ta Sy Pxlookup_by_addr_resolved
 245 .It Sy Pxlookup_by_name Ta Sy Pzonename
 246 .It Sy Pzonepath Ta Sy Pzoneroot Ta
 247 .El
 248 .Ss Thread interrogation and manipulation
 249 The following routines obtain information about a thread and allow
 250 manipulation of the thread itself.
 251 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 252 .It Sy Lalt_stack Ta Sy Lclearfault
 253 .It Sy Lclearsig Ta Sy Lctlfd
 254 .It Sy Ldstop Ta Sy Lgetareg
 255 .It Sy Lgetfpregs Ta Sy Lgetregs
 256 .It Sy Lgetxregs Ta Sy Lmain_stack
 257 .It Sy Lprochandle Ta Sy Lpsinfo
 258 .It Sy Lputareg Ta Sy Lsetrun
 259 .It Sy Lsetfpregs Ta Sy Lsetregs
 260 .It Sy Lsetxregs Ta Sy Lstack
 261 .It Sy Lstate Ta Sy Lstatus
 262 .It Sy Lstop Ta Sy Lsync
 263 .It Sy Lwait Ta Sy Lxecbkpt
 264 .It Sy Lxecwapt Ta Sy ""
 265 .El
 266 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 267 .It Sy Plwp_alt_stack Ta Sy Plwp_freexregs
 268 .It Sy Plwp_getfpregs Ta Sy Plwp_getname
 269 .It Sy Plwp_getpsinfo Ta Sy Plwp_getregs
 270 .It Sy Plwp_getspymaster Ta Sy Plwp_main_stack
 271 .It Sy Plwp_getxregs Ta Sy Plwp_setfpregs
 272 .It Sy Plwp_setregs Ta Sy Plwp_setxregs
 273 .It Sy Plwp_stack Ta Sy ""
 274 .El
 275 .Ss System Call Injection
 276 The following routines are used to inject specific system calls and have
 277 them run in the context of a process.
 278 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 279 .It Sy pr_access Ta Sy pr_close
 280 .It Sy pr_creat Ta Sy pr_door_info
 281 .It Sy pr_exit Ta Sy pr_fcntl
 282 .It Sy pr_fstat Ta Sy pr_fstat64
 283 .It Sy pr_fstatvfs Ta Sy pr_getitimer
 284 .It Sy pr_getpeername Ta Sy pr_getpeerucred
 285 .It Sy pr_getprojid Ta Sy pr_getrctl
 286 .It Sy pr_getrlimit Ta Sy pr_getrlimit64
 287 .It Sy pr_getsockname Ta Sy pr_getsockopt
 288 .It Sy pr_gettaskid Ta Sy pr_getzoneid
 289 .It Sy pr_ioctl Ta Sy pr_link
 290 .It Sy pr_llseek Ta Sy pr_lseek
 291 .It Sy pr_lstat Ta Sy pr_lstat64
 292 .It Sy pr_memcntl Ta Sy pr_meminfo
 293 .It Sy pr_mmap Ta Sy pr_munmap
 294 .It Sy pr_open Ta Sy pr_processor_bind

 329 .It Sy proc_str2content Ta Sy proc_str2flt
 330 .It Sy proc_str2fltset Ta Sy proc_str2sig
 331 .It Sy proc_str2sigset Ta Sy proc_str2sys
 332 .It Sy proc_str2sysset Ta Sy proc_sysname
 333 .It Sy proc_sysset2str Ta Sy proc_unctrl_psinfo
 334 .El
 335 .Ss x86 Specific Routines
 336 The following routines are specific to the x86, 32-bit and 64-bit,
 337 versions of the
 338 .Nm
 339 library.
 340 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 341 .It Sy Pldt Ta Sy proc_get_ldt
 342 .El
 343 .Ss SPARC specific Routines
 344 The following functions are specific to the SPARC, 32-bit and 64-bit,
 345 versions of the
 346 .Nm
 347 library.
 348 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 349 .It Sy Plwp_getgwindows Ta Sy ""

 350 .El
 351 .Pp
 352 The following functions are specific to the 64-bit SPARC version of the
 353 .Nm
 354 library.
 355 .Bl -column -offset indent ".Sy Pmapping_iter_resolved" ".Sy Psymbol_iter_by_addr"
 356 .It Sy Plwp_getasrs Ta Sy Plwp_setasrs
 357 .El
 358 .Sh PROCESS STATES
 359 Every process handle that exists in
 360 .Nm
 361 has a state.
 362 In some cases, such as for core files, these states are static.
 363 In other cases, such as handles that correspond to a running process or a
 364 created process, these states are dynamic and change based on actions taken in
 365 the library.
 366 The state can be obtained with the
 367 .Xr Pstate 3PROC
 368 function.
 369 .Pp