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 PZONENAME 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pzonename ,
  19 .Nm Pzoneroot ,
  20 .Nm Pzonepath
  21 .Nd get zone name, root, and full object path
  22 .Sh LIBRARY
  23 .Lb libproc
  24 .Sh SYNOPSIS
  25 .In libproc.h
  26 .Ft char *
  27 .Fo Pzonename
  28 .Fa "struct ps_prochandle *P"
  29 .Fa "char *buf"
  30 .Fa "size_t nbyte"
  31 .Fc
  32 .Ft char *
  33 .Fo Pzoneroot
  34 .Fa "struct ps_prochandle *P"
  35 .Fa "char *buf"
  36 .Fa "size_t nbyte"
  37 .Fc
  38 .Ft char *
  39 .Fo Pzonepath
  40 .Fa "struct ps_prochandle *P"
  41 .Fa "const char *path"
  42 .Fa "char *buf"
  43 .Fa "size_t nbyte"
  44 .Fc
  45 .Sh DESCRIPTION
  46 The
  47 .Fn Pzonename
  48 function attempts to determine the name of the zone for the process
  49 handle
  50 .Fa P .
  51 If found, up to
  52 .Fa nbytes ,
  53 including a null terminator, will be written into
  54 .Fa buf .
  55 .Pp
  56 The
  57 .Fn Pzoneroot
  58 function attempts to determine the root of the zone corresponding to the
  59 process handle
  60 .Fa P .
  61 If found, up to
  62 .Fa nbytes ,
  63 including a null terminator, will be written into
  64 .Fa buf .
  65 If the root cannot be found, for example a core file that did not
  66 originate on the current system, then the empty string will be written
  67 into
  68 .Fa buf .
  69 .Pp
  70 The
  71 .Fn Pzonepath
  72 function attempts to derive the full path of the object
  73 .Fa path
  74 in a zone relative to the root associated with the current process
  75 handle
  76 .Fa P .
  77 If found, up to
  78 .Fa nbytes ,
  79 including a null terminator, will be written into
  80 .Fa buf .
  81 It is legal to use the same buffer for both
  82 .Fa path
  83 and
  84 .Fa buf ;
  85 it will not be updated unless the function completes successfully.
  86 .Sh RETURN VALUES
  87 Upon successful completion, the
  88 .Fn Pzonename ,
  89 .Fn Pzoneroot ,
  90 and
  91 .Fn Pzonepath
  92 functions return
  93 .Sy buf .
  94 Otherwise, if an error occurred,
  95 .Dv NULL
  96 is returned and
  97 .Sy errno
  98 is set.
  99 .Sh ERRORS
 100 The
 101 .Fn Pzonename
 102 and
 103 .Fn Pzoneroot
 104 functions will fail if:
 105 .Bl -tag -width Er
 106 .It Er ENODATA
 107 .Fa P
 108 refers to a core file and zone information was not available in the core
 109 dump or
 110 .Fa P
 111 refers to an ELF object grabbed through
 112 .Xr Pgrab_file 3PROC .
 113 .It Er EFAULT
 114 .Fa P
 115 refers to an active process and
 116 .Fa buf
 117 is invalid.
 118 .El
 119 .Pp
 120 The
 121 .Fn Pzoneroot
 122 function will fail if:
 123 .Bl -tag -width Er
 124 .It Er ENOMEM
 125 Insufficient memory was available on the system.
 126 .El
 127 .Sh INTERFACE STABILITY
 128 .Sy Uncommitted
 129 .Sh MT-LEVEL
 130 See
 131 .Sy LOCKING
 132 in
 133 .Xr libproc 3LIB .
 134 .Sh SEE ALSO
 135 .Xr getzoneidbyname 3C ,
 136 .Xr libproc 3LIB ,
 137 .Xr proc 4