.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 11, 2016
.Dt PREAD 3PROC
.Os
.Sh NAME
.Nm Pread ,
.Nm Pread_string
.Nd read data from a process
.Sh LIBRARY
.Lb libproc
.Sh SYNOPSIS
.In libproc.h
.Ft ssize_t
.Fo Pread
.Fa "struct ps_prochandle *P"
.Fa "void *buf"
.Fa "size_t nbytes"
.Fa "uintptr_t address"
.Fc
.Ft ssize_t
.Fo Pread_string
.Fa "struct ps_prochandle *P"
.Fa "char *buf"
.Fa "size_t nbytes"
.Fa "uintptr_t address"
.Fc
.Sh DESCRIPTION
The
.Fn Pread
function reads data from the process handle
.Fa P
starting at
.Fa address
in the address space of the process and reads at most
.Fa nbytes
of data into
.Fa buf
and is logically analogous to the
.Xr pread 2
function.
.Pp
For live processes, this function is equivalent to reading from the /proc file
system
.Sy as
file for the process.
For core files and file handles, it reads and writes from the logical address
space and not the corresponding offset of the file itself.
For example, a core file contains a sparse representation of the address space
of a crashed process and unmapped regions are not present in the file.
However,
.Fa address
still refers to the virtual addresses that were present at run-time and
not those in the core file.
.Pp
The
.Fn Pread_string
function is similar to the
.Fn Pread
function, except that it attempts to interpret
.Fa address
as a null terminated character string and will stop reading characters
into
.Fa buf
if either
.Fa nbytes
has been read or a null terminator is encountered.
The resulting data in
.Fa buf
will always be null terminated, even if no null terminator was found in
the first
.Fa nbytes
of data.
.Sh RETURN VALUES
Upon successful completion, the
.Fn Pread
and
.Fn Pread_string
functions return a non-negative integer indicating the number of bytes
actually read.
Otherwise, the functions return
.Sy -1
and set
.Sy errno
to indicate the error.
.Sh ERRORS
For a full list of possible errors also see the
.Sy DIAGNOSTICS
section in
.Xr proc 5
and
the
.Sy ERRORS
section in
.Xr pread 2 .
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
See
.Sy LOCKING
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr pread 2 ,
.Xr libproc 3LIB ,
.Xr proc 5