usr/src/man/man3proc/Pread.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 PREAD 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pread ,
  19 .Nm Pread_string
  20 .Nd read data from a process
  21 .Sh LIBRARY
  22 .Lb libproc
  23 .Sh SYNOPSIS
  24 .In libproc.h
  25 .Ft ssize_t
  26 .Fo Pread
  27 .Fa "struct ps_prochandle *P"
  28 .Fa "void *buf"
  29 .Fa "size_t nbytes"
  30 .Fa "uintptr_t address"
  31 .Fc
  32 .Ft ssize_t
  33 .Fo Pread_string
  34 .Fa "struct ps_prochandle *P"
  35 .Fa "char *buf"
  36 .Fa "size_t nbytes"
  37 .Fa "uintptr_t address"
  38 .Fc
  39 .Sh DESCRIPTION
  40 The
  41 .Fn Pread
  42 function reads data from the process handle
  43 .Fa P
  44 starting at
  45 .Fa address
  46 in the address space of the process and reads at most
  47 .Fa nbytes
  48 of data into
  49 .Fa buf
  50 and is logically analogous to the
  51 .Xr pread 2
  52 function.
  53 .Pp
  54 For live processes, this function is equivalent to reading from the /proc file
  55 system
  56 .Sy as
  57 file for the process.
  58 For core files and file handles, it reads and writes from the logical address
  59 space and not the corresponding offset of the file itself.
  60 For example, a core file contains a sparse representation of the address space
  61 of a crashed process and unmapped regions are not present in the file.
  62 However,
  63 .Fa address
  64 still refers to the virtual addresses that were present at run-time and
  65 not those in the core file.
  66 .Pp
  67 The
  68 .Fn Pread_string
  69 function is similar to the
  70 .Fn Pread
  71 function, except that it attempts to interpret
  72 .Fa address
  73 as a null terminated character string and will stop reading characters
  74 into
  75 .Fa buf
  76 if either
  77 .Fa nbytes
  78 has been read or a null terminator is encountered.
  79 The resulting data in
  80 .Fa buf
  81 will always be null terminated, even if no null terminator was found in
  82 the first
  83 .Fa nbytes
  84 of data.
  85 .Sh RETURN VALUES
  86 Upon successful completion, the
  87 .Fn Pread
  88 and
  89 .Fn Pread_string
  90 functions return a non-negative integer indicating the number of bytes
  91 actually read.
  92 Otherwise, the functions return
  93 .Sy -1
  94 and set
  95 .Sy errno
  96 to indicate the error.
  97 .Sh ERRORS
  98 For a full list of possible errors also see the
  99 .Sy DIAGNOSTICS
 100 section in
 101 .Xr proc 4
 102 and
 103 the
 104 .Sy ERRORS
 105 section in
 106 .Xr pread 2 .
 107 .Sh INTERFACE STABILITY
 108 .Sy Uncommitted
 109 .Sh MT-LEVEL
 110 See
 111 .Sy LOCKING
 112 in
 113 .Xr libproc 3LIB .
 114 .Sh SEE ALSO
 115 .Xr pread 2 ,
 116 .Xr libproc 3LIB ,
 117 .Xr proc 4