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