lib/libc/sys/minherit.2

   1 .\"
   2 .\" Copyright (c) 1991, 1993
   3 .\"     The Regents of the University of California.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. Neither the name of the University nor the names of its contributors
  14 .\"    may be used to endorse or promote products derived from this software
  15 .\"    without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .Dd March 15, 2017
  30 .Dt MINHERIT 2
  31 .Os
  32 .Sh NAME
  33 .Nm minherit
  34 .Nd control the inheritance of pages
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In sys/mman.h
  39 .Ft int
  40 .Fn minherit "void *addr" "size_t len" "int inherit"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn minherit
  44 system call
  45 changes the specified pages to have the inheritance characteristic
  46 .Fa inherit .
  47 Not all implementations will guarantee that the inheritance characteristic
  48 can be set on a page basis;
  49 the granularity of changes may be as large as an entire region.
  50 .Fx
  51 is capable of adjusting inheritance characteristics on a page basis.
  52 Inheritance only effects children created by
  53 .Fn fork .
  54 It has no effect on
  55 .Fn exec .
  56 exec'd processes replace their address space entirely.
  57 This system call also
  58 has no effect on the parent's address space (other than to potentially
  59 share the address space with its children).
  60 .Pp
  61 Inheritance is a rather esoteric feature largely superseded by the
  62 .Dv MAP_SHARED
  63 feature of
  64 .Fn mmap .
  65 However, it is possible to use
  66 .Fn minherit
  67 to share a block of memory between parent and child that has been mapped
  68 .Dv MAP_PRIVATE .
  69 That is, modifications made by parent or child are shared but
  70 the original underlying file is left untouched.
  71 .Bl -tag -width ".Dv INHERIT_SHARE"
  72 .It Dv INHERIT_SHARE
  73 This option causes the address space in question to be shared between
  74 parent and child.
  75 It has no effect on how the original underlying backing
  76 store was mapped.
  77 .It Dv INHERIT_NONE
  78 This option prevents the address space in question from being inherited
  79 at all.
  80 The address space will be unmapped in the child.
  81 .It Dv INHERIT_COPY
  82 This option causes the child to inherit the address space as copy-on-write.
  83 This option also has an unfortunate side effect of causing the parent
  84 address space to become copy-on-write when the parent forks.
  85 If the original mapping was
  86 .Dv MAP_SHARED ,
  87 it will no longer be shared in the parent
  88 after the parent forks and there is no way to get the previous
  89 shared-backing-store mapping without unmapping and remapping the address
  90 space in the parent.
  91 .It Dv INHERIT_ZERO
  92 This option causes the address space in question to be mapped as new
  93 anonymous pages,
  94 which would be initialized to all zero bytes,
  95 in the child process.
  96 .El
  97 .Sh RETURN VALUES
  98 .Rv -std minherit
  99 .Sh ERRORS
 100 The
 101 .Fn minherit
 102 system call will fail if:
 103 .Bl -tag -width Er
 104 .It Bq Er EINVAL
 105 The virtual address range specified by the
 106 .Fa addr
 107 and
 108 .Fa len
 109 arguments is not valid.
 110 .It Bq Er EACCES
 111 The flags specified by the
 112 .Fa inherit
 113 argument were not valid for the pages specified
 114 by the
 115 .Fa addr
 116 and
 117 .Fa len
 118 arguments.
 119 .El
 120 .Sh SEE ALSO
 121 .Xr fork 2 ,
 122 .Xr madvise 2 ,
 123 .Xr mincore 2 ,
 124 .Xr mprotect 2 ,
 125 .Xr msync 2 ,
 126 .Xr munmap 2 ,
 127 .Xr rfork 2
 128 .Sh HISTORY
 129 The
 130 .Fn minherit
 131 system call first appeared in
 132 .Ox
 133 and then in
 134 .Fx 2.2 .
 135 .Pp
 136 The
 137 .Dv INHERIT_ZERO
 138 support first appeared in
 139 .Ox 5.6
 140 and then in
 141 .Fx 12.0 .
 142 .Sh BUGS
 143 Once you set inheritance to
 144 .Dv MAP_PRIVATE
 145 or
 146 .Dv MAP_SHARED ,
 147 there is no way to recover the original copy-on-write semantics
 148 short of unmapping and remapping the area.