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