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