usr/src/man/man3proc/Pwrite.3proc

   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 PWRITE 3PROC
  16 .Os
  17 .Sh NAME
  18 .Nm Pwrite
  19 .Nd write data to the address space of a process
  20 .Sh LIBRARY
  21 .Lb libproc
  22 .Sh SYNOPSIS
  23 .In libproc.h
  24 .Ft ssize_t
  25 .Fo Pwrite
  26 .Fa "struct ps_prochandle *P"
  27 .Fa "const void *buf"
  28 .Fa "size_t nbyte"
  29 .Fa "uintptr_t address"
  30 .Fc
  31 .Sh DESCRIPTION
  32 The
  33 .Fn Pwrite
  34 function writes data from
  35 .Fa buf
  36 to the process handle
  37 .Fa P
  38 starting at the address
  39 .Fa address .
  40 It writes at most
  41 .Fa nbyte
  42 of data.
  43 The
  44 .Fn Pwrite
  45 function is logically analogous to the
  46 .Xr pwrite 2
  47 function.
  48 .Pp
  49 For live processes, this function is equivalent to writing to the
  50 /proc file system
  51 .Sy as
  52 file for the process.
  53 For core files, it writes to the logical address space of what was once the
  54 process and not the corresponding offset in the on-disk file.
  55 ELF objects grabbed through
  56 .Xr Pgrab_file 3PROC
  57 do not support being written to.
  58 .Pp
  59 The
  60 .Fn Pwrite
  61 function cannot be used to
  62 .Em extend
  63 the size of a mapping; writing to an unmapped region generates an
  64 error.
  65 .Sh RETURN VALUES
  66 Upon successful completion, the
  67 .Fn Pwrite
  68 function returns the number of bytes successfully written to
  69 .Fa P .
  70 This number is never greater than
  71 .Fa nbyte .
  72 Otherwise, it returns
  73 .Sy -1
  74 and
  75 .Sy errno
  76 is set to indicate an error.
  77 For the full list of errors see the
  78 .Sy DIAGNOSTICS
  79 section in
  80 .Xr proc 4
  81 and
  82 the
  83 .Sy ERRORS
  84 section in
  85 .Xr pwrite 2 .
  86 .Pp
  87 In addition, the
  88 .Fn Pwrite
  89 function will fail if:
  90 .Bl -tag -width Er
  91 .It Er EIO
  92 .Fa P
  93 refers to an ELF object and not a core file or active process.
  94 .El
  95 .Sh INTERFACE STABILITY
  96 .Sy Uncommitted
  97 .Sh MT-LEVEL
  98 See
  99 .Sy LOCKING
 100 in
 101 .Xr libproc 3LIB .
 102 .Sh SEE ALSO
 103 .Xr pwrite 2 ,
 104 .Xr libproc 3LIB ,
 105 .Xr proc 4