svn commit: r334439 - stable/11/lib/libc/sys

[Brooks Davis]

Author: brooks
Date: Thu May 31 16:01:10 2018
New Revision: 334439
URL: https://svnweb.freebsd.org/changeset/base/334439

Log:
  MFC r334176:
  
  Indicate the brk/sbrk are deprecated and not portable.
  
  More firmly suggest mmap(2) instead.
  
  Include the history of arm64 and riscv shipping without brk/sbrk.
  
  Mention that sbrk(0) produces unreliable results.
  
  Approved by:	re (kib)
  Reviewed by:	emaste, Marcin Cieślak
  Sponsored by:	DARPA, AFRL
  Differential Revision:	https://reviews.freebsd.org/D15535

Modified:
  stable/11/lib/libc/sys/brk.2
Directory Properties:
  stable/11/   (props changed)

Modified: stable/11/lib/libc/sys/brk.2
==============================================================================
--- stable/11/lib/libc/sys/brk.2	Thu May 31 16:00:03 2018	(r334438)
+++ stable/11/lib/libc/sys/brk.2	Thu May 31 16:01:10 2018	(r334439)
@@ -28,7 +28,7 @@
 .\"     @(#)brk.2	8.4 (Berkeley) 5/1/95
 .\" $FreeBSD$
 .\"
-.Dd December 15, 2015
+.Dd May 24, 2018
 .Dt BRK 2
 .Os
 .Sh NAME
@@ -51,6 +51,10 @@ and
 .Fn sbrk
 functions are legacy interfaces from before the
 advent of modern virtual memory management.
+They are deprecated and not present on the arm64 or riscv architectures.
+The
+.Xr mmap 2
+interface should be used to allocate pages instead.
 .Ef
 .Pp
 The
@@ -152,6 +156,11 @@ The
 .Fn brk
 function appeared in
 .At v7 .
+.Fx 11.0
+introduced the arm64 and riscv architectures which do not support
+.Fn brk
+or
+.Fn sbrk .
 .Sh BUGS
 Mixing
 .Fn brk
@@ -168,3 +177,9 @@ It is not possible to distinguish this
 from a failure caused by exceeding the maximum size of
 the data segment without consulting
 .Xr getrlimit 2 .
+.Pp
+.Fn sbrk
+is sometimes used to monitor heap use by calling with an argument of 0.
+The result is unlikely to reflect actual utilization in combination with an
+.Xr mmap 2
+based malloc.