usr/src/man/man3kvm/kvm_getu.3kvm

   1 '\" te
   2 .\"  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH KVM_GETU 3KVM "May 2, 2002"
   7 .SH NAME
   8 kvm_getu, kvm_getcmd \- get the u-area or invocation arguments for a process
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkvm\fR [ \fIlibrary\fR\&.\|.\|.]
  13 #include <kvm.h>
  14 #include <sys/param.h>
  15 #include <sys/user.h>
  16 #include <sys/proc.h>
  17
  18 \fBstruct user *\fR\fBkvm_getu\fR(\fBkvm_t *\fR\fIkd\fR, \fBstruct proc *\fR\fIproc\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBkvm_getcmd\fR(\fBkvm_t *\fR\fIkd\fR, \fBstruct proc *\fR\fIproc\fR, \fBstruct user *\fR\fIu\fR, \fBchar ***\fR\fIarg\fR,
  24      \fBchar ***\fR\fIenv\fR);
  25 .fi
  26
  27 .SH DESCRIPTION
  28 .sp
  29 .LP
  30 The \fBkvm_getu()\fR function reads the u-area of the process specified by
  31 \fIproc\fR to an area of static storage associated with \fIkd\fR and returns a
  32 pointer to it. Subsequent calls to \fBkvm_getu()\fR will overwrite this static
  33 area.
  34 .sp
  35 .LP
  36 The \fIkd\fR argument is a pointer to a kernel descriptor returned by
  37 \fBkvm_open\fR(3KVM). The \fIproc\fR argument is a pointer to a copy in the
  38 current process's address space of a \fIproc\fR structure, obtained, for
  39 instance, by a prior \fBkvm_nextproc\fR(3KVM) call.
  40 .sp
  41 .LP
  42 The \fBkvm_getcmd()\fR function constructs a list of string pointers that
  43 represent the command arguments and environment that were used to initiate the
  44 process specified by \fIproc\fR.
  45 .sp
  46 .LP
  47 The \fIkd\fR argument is a pointer to a kernel descriptor returned by
  48 \fBkvm_open\fR(3KVM). The \fIu\fR argument is a pointer to a copy in the
  49 current process's address space of a \fBuser\fR structure, obtained, for
  50 instance, by a prior \fBkvm_getu()\fR call. If \fIarg\fR is not \fINULL\fR, the
  51 command line arguments are formed into a null-terminated array of string
  52 pointers. The address of the first such pointer is returned in \fIarg\fR. If
  53 \fIenv\fR is not \fINULL\fR, the environment is formed into a null-terminated
  54 array of string pointers.  The address of the first of these is returned in
  55 \fIenv\fR.
  56 .sp
  57 .LP
  58 The pointers returned in \fIarg\fR and \fIenv\fR refer to data allocated by
  59 \fBmalloc()\fR and should be freed by a call to \fBfree()\fR when no longer
  60 needed. See \fBmalloc\fR(3C). Both the string pointers and the strings
  61 themselves are deallocated when freed.
  62 .sp
  63 .LP
  64 Since the environment and command line arguments might have been modified by
  65 the user process, there is no guarantee that it will be possible to reconstruct
  66 the original command at all.  The \fBkvm_getcmd()\fR function will make the
  67 best attempt possible, returning \(mi1 if the user process data is
  68 unrecognizable.
  69 .SH RETURN VALUES
  70 .sp
  71 .LP
  72 On success, \fBkvm_getu()\fR returns a pointer to a copy of the u-area of the
  73 process specified by \fIproc\fR. On failure, it returns \fINULL\fR.
  74 .sp
  75 .LP
  76 The \fBkvm_getcmd()\fR function returns 0 on success and \(mi1 on failure. If
  77 \(mi1 is returned, the caller still has the option of using the command line
  78 fragment that is stored in the u-area.
  79 .SH ATTRIBUTES
  80 .sp
  81 .LP
  82 See \fBattributes\fR(5) for descriptions of the following attributes:
  83 .sp
  84
  85 .sp
  86 .TS
  87 box;
  88 c | c
  89 l | l .
  90 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  91 _
  92 Interface Stability     Stable
  93 _
  94 MT-Level        Unsafe
  95 .TE
  96
  97 .SH SEE ALSO
  98 .sp
  99 .LP
 100 \fBkvm_nextproc\fR(3KVM), \fBkvm_open\fR(3KVM), \fBkvm_kread\fR(3KVM),
 101 \fBmalloc\fR(3C), \fBlibkvm\fR(3LIB), \fBattributes\fR(5)
 102 .SH NOTES
 103 .sp
 104 .LP
 105 On systems that support both 32-bit and 64-bit processes, the 64-bit
 106 implementation of \fBlibkvm\fR ensures that the \fIarg\fR and \fBenv\fR pointer
 107 arrays for \fBkvm_getcmd()\fR are translated to the same form as if they were
 108 64-bit processes.  Applications that wish to access the raw 32-bit stack
 109 directly can use \fBkvm_uread()\fR. See \fBkvm_read\fR(3KVM).