lib/libc/sys/sbrk.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)brk.2       8.4 (Berkeley) 5/1/95
  29 .\" $FreeBSD: src/lib/libc/sys/brk.2,v 1.13.2.10 2002/03/04 12:00:31 dwmalone Exp $
  30 .\"
  31 .Dd March 1, 2019
  32 .Dt SBRK 2
  33 .Os
  34 .Sh NAME
  35 .Nm sbrk
  36 .Nd change data segment size (obsolete)
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In unistd.h
  42 .Ft void *
  43 .Fn sbrk "intptr_t incr"
  44 .Sh DESCRIPTION
  45 .Bf -symbolic
  46 The
  47 .Fn sbrk
  48 function is a legacy interface from before the
  49 advent of modern virtual memory management.
  50 .Fn sbrk
  51 has only limited functionality due to having to play nice with
  52 modern system calls such as
  53 .Xr mmap 2 .
  54 .Ef
  55 .Pp
  56 The
  57 .Fn sbrk
  58 function is used to change the amount of memory allocated in a
  59 process's data segment.
  60 It does this by moving the location of the
  61 .Dq break .
  62 The break is the first address after the end of the process's
  63 uninitialized data segment (also known as the
  64 .Dq BSS ) .
  65 .Pp
  66 The break range is limited by the
  67 .Dv RLIMIT_DATA
  68 resource limit applied to the process.
  69 .Pp
  70 The
  71 .Fn sbrk
  72 function raises the break by
  73 .Fa incr
  74 bytes, returning a pointer to the base of the new memory.
  75 Any attempt to lower the break point will return
  76 .Po Vt "void *" Pc Ns \-1
  77 and set errno to
  78 .Er EOPNOTSUPP .
  79 .Sh NOTES
  80 While the actual process data segment size maintained by the kernel will only
  81 grow or shrink in page sizes, this function allows setting the break
  82 to unaligned values (i.e., it may point to any address inside the last
  83 page of the data segment).
  84 .Pp
  85 The current value of the program break may be determined by calling
  86 .Fn sbrk 0 .
  87 .Pp
  88 The
  89 .Fn sbrk
  90 function is thread-safe.
  91 See also
  92 .Xr end 3 .
  93 .Pp
  94 The
  95 .Xr getrlimit 2
  96 system call may be used to determine
  97 the maximum permissible size of the
  98 data segment.
  99 It will not be possible to set the break
 100 beyond
 101 .Dq Va etext No + Va rlim.rlim_max
 102 where the
 103 .Va rlim.rlim_max
 104 value is returned from a call to
 105 .Fn getrlimit RLIMIT_DATA &rlim .
 106 (See
 107 .Xr end 3
 108 for the definition of
 109 .Va etext ) .
 110 .Sh RETURN VALUES
 111 The
 112 .Fn sbrk
 113 function returns the prior break pointer if successful;
 114 otherwise the value
 115 .Po Vt "void *" Pc Ns \-1
 116 is returned and the global variable
 117 .Va errno
 118 is set to indicate the error.
 119 .Sh ERRORS
 120 .Fn sbrk
 121 will fail if:
 122 .Bl -tag -width Er
 123 .It Bq Er EINVAL
 124 The requested break value was beyond the beginning of the data segment.
 125 .It Bq Er ENOMEM
 126 The data segment size limit, as set by
 127 .Xr setrlimit 2 ,
 128 was exceeded.
 129 .It Bq Er ENOMEM
 130 Insufficient space existed in the swap area
 131 to support the expansion of the data segment.
 132 .It Bq Er EOPNOTSUPP
 133 An attempt has been made to perform an action that is no longer supported
 134 by this function.
 135 .El
 136 .Sh SEE ALSO
 137 .Xr execve 2 ,
 138 .Xr getrlimit 2 ,
 139 .Xr mmap 2 ,
 140 .Xr end 3 ,
 141 .Xr free 3 ,
 142 .Xr malloc 3
 143 .Sh BUGS
 144 Mixing
 145 .Fn sbrk
 146 with
 147 .Xr malloc 3 ,
 148 .Xr free 3 ,
 149 or similar functions will result in non-portable program behavior.
 150 .Pp
 151 Setting the break may fail due to a temporary lack of
 152 swap space.
 153 It is not possible to distinguish this
 154 from a failure caused by exceeding the maximum size of
 155 the data segment without consulting
 156 .Xr getrlimit 2 .