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