Module Name: src Committed By: jruoho Date: Mon May 3 03:47:51 UTC 2010
Modified Files: src/lib/libc/stdlib: malloc.3 Log Message: Add more markup. To generate a diff of this commit: cvs rdiff -u -r1.33 -r1.34 src/lib/libc/stdlib/malloc.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/lib/libc/stdlib/malloc.3 diff -u src/lib/libc/stdlib/malloc.3:1.33 src/lib/libc/stdlib/malloc.3:1.34 --- src/lib/libc/stdlib/malloc.3:1.33 Fri Apr 30 07:16:35 2010 +++ src/lib/libc/stdlib/malloc.3 Mon May 3 03:47:51 2010 @@ -1,4 +1,4 @@ -.\" $NetBSD: malloc.3,v 1.33 2010/04/30 07:16:35 jruoho Exp $ +.\" $NetBSD: malloc.3,v 1.34 2010/05/03 03:47:51 jruoho Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -34,7 +34,7 @@ .\" @(#)malloc.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $ .\" -.Dd April 30, 2010 +.Dd May 3, 2010 .Dt MALLOC 3 .Os .Sh NAME @@ -188,13 +188,13 @@ where uppercase indicates that the behavior is set, or on, and lowercase means that the behavior is not set, or off. .Bl -tag -width indent -.It A +.It Em A All warnings (except for the warning about unknown flags being set) become fatal. The process will call .Xr abort 3 in these cases. -.It H +.It Em H Use .Xr madvise 2 when pages within a chunk are no longer in use, but the chunk as a whole cannot @@ -203,7 +203,7 @@ overhead of the .Fn madvise system call. -.It J +.It Em J Each byte of new memory allocated by .Fn malloc , .Fn realloc @@ -213,16 +213,16 @@ .Fn realloc will be initialized to 0x5a. This is intended for debugging and will impact performance negatively. -.It K +.It Em K Increase/decrease the virtual memory chunk size by a factor of two. The default chunk size is 1 MB. This option can be specified multiple times. -.It N +.It Em N Increase/decrease the number of arenas by a factor of two. The default number of arenas is four times the number of CPUs, or one if there is a single CPU. This option can be specified multiple times. -.It P +.It Em P Various statistics are printed at program exit via an .Xr atexit 3 function. @@ -230,25 +230,25 @@ while one or more threads are executing in the memory allocation functions. Therefore, this option should only be used with care; it is primarily intended as a performance tuning aid during application development. -.It Q +.It Em Q Increase/decrease the size of the allocation quantum by a factor of two. The default quantum is the minimum allowed by the architecture (typically 8 or 16 bytes). This option can be specified multiple times. -.It S +.It Em S Increase/decrease the size of the maximum size class that is a multiple of the quantum by a factor of two. Above this size, power-of-two spacing is used for size classes. The default value is 512 bytes. This option can be specified multiple times. -.It U +.It Em U Generate .Dq utrace entries for .Xr ktrace 1 , for all operations. Consult the source for details on this option. -.It V +.It Em V Attempting to allocate zero bytes will return a .Dv NULL pointer instead of a valid pointer. @@ -256,9 +256,9 @@ pointer to it.) This option is provided for System V compatibility. This option is incompatible with the -.Dq X +.Em X option. -.It X +.It Em X Rather than return failure for any allocation function, display a diagnostic message on .Dv stderr @@ -270,7 +270,8 @@ .Bd -literal -offset indent _malloc_options = "X"; .Ed -.It Z +.Pp +.It Em Z Each byte of new memory allocated by .Fn malloc , .Fn realloc @@ -282,9 +283,9 @@ .El .Pp The -.Dq J +.Em J and -.Dq Z +.Em Z options are intended for testing and debugging. An application which changes its behavior when these options are used is flawed. @@ -327,18 +328,18 @@ Small objects are managed in groups by page runs. Each run maintains a bitmap that tracks which regions are in use. Allocation requests that are no more than half the quantum (see the -.Dq Q +.Em Q option) are rounded up to the nearest power of two (typically 2, 4, or 8). Allocation requests that are more than half the quantum, but no more than the maximum quantum-multiple size class (see the -.Dq S +.Em S option) are rounded up to the nearest multiple of the quantum. Allocation requests that are larger than the maximum quantum-multiple size class, but no larger than one half of a page, are rounded up to the nearest power of two. Allocation requests that are larger than half of a page, but small enough to fit in an arena-managed chunk (see the -.Dq K +.Em K option), are rounded up to the nearest run size. Allocation requests that are too large to fit in an arena-managed chunk are rounded up to the nearest multiple of the chunk size. @@ -350,7 +351,7 @@ size. .Sh DEBUGGING MALLOC PROBLEMS The first thing to do is to set the -.Dq A +.Em A option. This option forces a coredump (if possible) at the first sign of trouble, rather than the normal policy of trying to continue if at all possible. @@ -363,18 +364,18 @@ section, it is likely because it depends on the storage being filled with zero bytes. Try running it with the -.Dq Z +.Em Z option set; if that improves the situation, this diagnosis has been confirmed. If the program still misbehaves, the likely problem is accessing memory outside the allocated area. .Pp Alternatively, if the symptoms are not easy to reproduce, setting the -.Dq J +.Em J option may help provoke the problem. .Pp In truly difficult cases, the -.Dq U +.Em U option, if supported by the kernel, can provide a detailed trace of all calls made to these functions. .Pp @@ -390,7 +391,7 @@ .Dv STDERR_FILENO . Errors will result in the process dumping core. If the -.Dq A +.Em A option is set, all warnings are treated as errors. .Pp The