usr/src/man/man3proc/Pgcore.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 November 27, 2023
  15 .Dt PGCORE 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pfgcore ,
  19 .Nm Pgcore
  20 .Nd produce a core file of a process
  21 .Sh LIBRARY
  22 .Lb libproc
  23 .Sh SYNOPSIS
  24 .In libproc.h
  25 .Ft int
  26 .Fo Pfgcore
  27 .Fa "struct ps_prochandle *P"
  28 .Fa "int fd"
  29 .Fa "core_content_t content"
  30 .Fc
  31 .Ft int
  32 .Fo Pgcore
  33 .Fa "struct ps_prochandle *P"
  34 .Fa "const char *fname"
  35 .Fa "core_content_t content"
  36 .Fc
  37 .Sh DESCRIPTION
  38 The
  39 .Fn Pgcore
  40 and
  41 .Fn Pfgcore
  42 functions produce core files of the handle referred to by
  43 .Fa P .
  44 Core files represent a snapshot of a process and may be manipulated by a
  45 wide variety of tools and libraries including
  46 .Xr libproc 3LIB ,
  47 .Xr mdb 1 ,
  48 .Xr pargs 1 ,
  49 .Xr pstack 1 ,
  50 and more.
  51 For details on the core file format, see
  52 .Xr core 5 .
  53 .Pp
  54 .Fn Pfgcore
  55 writes the core to the file represented by the open descriptor
  56 .Fa fd .
  57 The file descriptor should be open for both read and write.
  58 .Fn Pgcore
  59 writes the core to the file path
  60 .Fa fname .
  61 .Pp
  62 The content of the core is controlled by the
  63 .Fa content
  64 argument.
  65 It's the inclusive-bitwise-OR of the various content types listed under the
  66 .Sy core_content_t
  67 heading in the
  68 .Sy TYPES
  69 section in
  70 .Xr libproc 3LIB .
  71 Using
  72 .Dv CC_CONTENT_INVALID
  73 is illegal and will result in an error.
  74 .Pp
  75 Neither the
  76 .Fn Pgcore
  77 or
  78 .Fn Pfgcore
  79 functions stop the handle
  80 .Fa P .
  81 It is up to the caller to stop the process; which is recommended for
  82 obtaining a consistent view of the process.
  83 See the
  84 .Xr Pstop 3PROC
  85 function for a means to stop a handle.
  86 .Sh RETURN VALUES
  87 Upon successful completion, the
  88 .Fn Pfcore
  89 and
  90 .Fn Pgcore
  91 functions return
  92 .Sy 0
  93 and write out a core file to specified location.
  94 Otherwise,
  95 .Sy -1
  96 is returned.
  97 The
  98 .Fn Pfgcore
  99 function will truncate
 100 .Fa fd
 101 and the
 102 .Fn Pgcore
 103 function will remove
 104 .Fa fname .
 105 .Sh INTERFACE STABILITY
 106 .Sy Uncommitted
 107 .Sh MT-LEVEL
 108 See
 109 .Sy LOCKING
 110 in
 111 .Xr libproc 3LIB .
 112 .Sh SEE ALSO
 113 .Xr libproc 3LIB ,
 114 .Xr Pstop 3PROC ,
 115 .Xr core 5 ,
 116 .Xr proc 5 ,
 117 .Xr coreadm 8