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