Bug#281903: glibc-doc: mallopt documentation is lacking

[Lars Wirzenius <lars.wirzenius@nokia.com>]

Package: glibc-doc
Version: 2.3.2.ds1-18
Severity: normal

The glibc documentation for mallopt does not describe its return value.
Nor does it document all parameter values (M_MXFAST is missing).
>From the source:

  mallopt(int parameter_number, int parameter_value)
  Sets tunable parameters The format is to provide a
  (parameter-number, parameter-value) pair.  mallopt then sets the
  corresponding parameter to the argument value if it can (i.e., so
  long as the value is meaningful), and returns 1 if successful else
  0.  SVID/XPG/ANSI defines four standard param numbers for mallopt,
  normally defined in malloc.h.  Only one of these (M_MXFAST) is used
  in this malloc. The others (M_NLBLKS, M_GRAIN, M_KEEP) don't apply,
  so setting them has no effect. But this malloc also supports four
  other options in mallopt. See below for details.  Briefly, supported
  parameters are as follows (listed defaults are for "typical"
  configurations).

  Symbol            param #   default    allowed param values
  M_MXFAST          1         64         0-80  (0 disables fastbins)
  M_TRIM_THRESHOLD -1         128*1024   any   (-1U disables trimming)
  M_TOP_PAD        -2         0          any
  M_MMAP_THRESHOLD -3         128*1024   any   (or 0 if no MMAP support)
  M_MMAP_MAX       -4         65536      any   (0 disables use of mmap)

I propose the following text to be added to the section "Malloc Tunable
Parameters" in the glibc documentation:

  M_MXFAST
	This is the maximum request size used for "fast bins", special bins
  	that hold returned chunks without consolidating their spaces.  This
  	enables future requests for chunks of the same size to be handled
  	very quickly, but can increase fragmentation, and thus increase the
  	overall memory footprint of a program.

Additionally, reading the code of the function (search for /^int mALLOPt/)
reveals the value M_CHECK_ACTION, which seems to enable some forms of
error checking and reporting inside the malloc implementation. I'm not 
how it works, so I won't offer text for that.


-- System Information:
Debian Release: 3.1
  APT prefers unstable
  APT policy: (500, 'unstable')
Architecture: i386 (i686)
Kernel: Linux 2.6.8-1-686
Locale: LANG=fi_FI.UTF-8, LC_CTYPE=fi_FI.UTF-8 (charmap=UTF-8)

-- no debconf information