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