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