*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> Tcl/memory (3)              


Memory(3Tcl)							  Memory(3Tcl)

NAME    [Toc]    [Back]

     ckalloc, memory, ckfree, Tcl_DisplayMemory, Tcl_InitMemory,
     Tcl_ValidateAllMemory - Validated memory allocation interface.

SYNOPSIS    [Toc]    [Back]

     memory info

     memory trace [on|off]

     memory validate [on|off]

     memory trace_on_at_malloc nnn

     memory break_on_malloc nnn

     memory display file

     #include <tcl.h>

     char *
     ckalloc (unsigned size)

     ckfree (char *ptr)

     Tcl_DumpActiveMemory (char	*fileName);

     Tcl_ValidateAllMemory (char *file,
			    int	  line)

     Tcl_InitMemory (interp)

ARGUMENTS    [Toc]    [Back]

     A pointer to the Tcl interpreter.	The filename of	the caller of
     Tcl_ValidateAllMemory.  The line number of	the caller of
     Tcl_ValidateAllMemory.  File to display list of active memory.

DESCRIPTION    [Toc]    [Back]

     Thi macro allocates memory, in the	same manner as malloc, with the
     following differences: One, ckalloc checks	the value returned from	malloc
     (it calls malloc for you) and panics if the allocation request fails.
     Two, if enabled at	compile	time, a	version	of ckalloc with	special	memory
     debugging capabilities replaces the normal	version	of ckalloc, which aids
     in	detecting memory overwrites and	leaks (repeated	allocations not
     matched by	corresponding frees).

									Page 1

Memory(3Tcl)							  Memory(3Tcl)

       o size -	The size of the	memory block to	be allocated.

       A pointer to the	allocated memory block.

     This macro	frees memory allocated by ckalloc.  Like ckalloc, when memory
     debugging is enabled, ckfree has enhanced capabilities for	detecting
     memory overwrites and leaks.

     It	is very	important that you use ckalloc when you	need to	allocate
     memory, and that you use ckfree to	free it.  Should you use malloc	to
     allocate and ckfree to free, spurious memory validation errors will occur
     when memory debugging is enabled.	Should you use free to free memory
     allocated by ckalloc, memory corruption will occur	when memory debugging
     is	enabled.  Any memory that is to	be become the property of the Tcl
     interpreter, such as result space,	must be	allocated with ckalloc.	 If it
     is	absolutely necessary for an application	to pass	back malloced memory
     to	Tcl, it	will work only if Tcl is complied with the TCL_MEM_DEBUG flag
     turned off.  If you convert your application to use this facility,	it
     will help you find	memory over runs and lost memory.  Note	that memory
     allocated by a C library routine requiring	freeing	should still be	freed
     with free,	since it calls malloc rather than ckalloc to do	the

       o ptr - The address of a	block to free, as returned by ckalloc.

   Tcl_DumpActiveMemory    [Toc]    [Back]
     This function will	output a list of all currently allocated memory	to the
     specified file.  The following information	is outputed for	each allocated
     block of memory: starting and ending addresses (excluding guard zone),
     size, source file where ckalloc was called	to allocate the	block and line
     number in that file.  It is especially useful to call
     Tcl_DumpActiveMemory after	the Tcl	interpreter has	been deleted.

       o fileName - The	name of	the file to output the memory list to.

   Tcl_ValidateAllMemory    [Toc]    [Back]
     Forces a validation of the	guard zones of all currently allocated blocks
     of	memory.	 Normally validation of	a block	occures	when its freed,	unless
     full validation is	enabled, in which case validation of all blocks	occurs
     when ckalloc and ckfree are called.  This function	forces the validation
     to	occur at any point.

       o file -	The file that this routine is being called from, normally
       o line -	The line that this routine is being called from, normally
Memory(3Tcl)							  Memory(3Tcl)


     To	enable memory debugging, Tcl should be recompiled from scratch with
     TCL_MEM_DEBUG defined.  This will also compile in a non-stub version of
     Tcl_InitMemory to add the memory command to Tcl.

     TCL_MEM_DEBUG must	be either left defined for all modules or undefined
     for all modules that are going to be linked together.  If they are	not,
     link errors will occur, with either TclDbCkfree and Tcl_DbCkalloc or
     Tcl_Ckalloc and Tcl_Ckfree	being undefined.

GUARD ZONES    [Toc]    [Back]

     When memory debugging is enabled, whenever	a call to ckalloc is made,
     slightly more memory than requested is allocated so the memory debugging
     code can keep track of the	allocated memory, and also eight-byte ``guard
     zones'' are placed	in front of and	behind the space that will be returned
     to	the caller.  (The size of the guard zone is defined by the C #define
     GUARD_SIZE	in baseline/src/ckalloc.c -- it	can be extended	if you suspect
     large overwrite problems, at some cost in performance.)  A	known pattern
     is	written	into the guard zones and, on a call to ckfree, the guard zones
     of	the space being	freed are checked to see if either zone	has been
     modified in any way.  If one has been, the	guard bytes and	their new
     contents are identified, and a ``low guard	failed'' or ``high guard
     failed'' message is issued.  The ``guard failed'' message includes	the
     address of	the memory packet and the file name and	line number of the
     code that called ckfree.  This allows you to detect the common sorts of
     one-off problems, where not enough	space was allocated to contain the
     data written, for example.

THE MEMORY COMMAND    [Toc]    [Back]

     memory options
	  The Tcl memory command gives the Tcl developer control of Tcl's
	  memory debugging capabilities.  The memory command has several
	  suboptions, which are	described below.  It is	only available when
	  Tcl has been compiled	with memory debugging enabled.

     memory info
	  Produces a report containing the total allocations and frees since
	  Tcl began, the current packets allocated (the	current	number of
	  calls	to ckalloc not met by a	corresponding call to ckfree), the
	  current bytes	allocated, and the maximum number of packets and bytes

     memory trace [on|off]
	  Turns	memory tracing on or off.  When	memory tracing is on, every
	  call to ckalloc causes a line	of trace information to	be written to
	  stderr, consisting of	the word ckalloc, followed by the address
	  returned, the	amount of memory allocated, and	the C filename and
	  line number of the code performing the allocation, for example...

	     ckalloc 40e478 98 tclProc.c 1406

									Page 3

Memory(3Tcl)							  Memory(3Tcl)

	  Calls	to ckfree are traced in	the same manner, except	that the word
	  ckalloc is replaced by the word ckfree.

     memory validate [on|off]
	  Turns	memory vaidation on or off.  When memory validation is
	  enabled, on every call to ckalloc or ckfree, the guard zones are
	  checked for every piece of memory currently in existence that	was
	  allocated by ckalloc.	 This has a large performance impact and
	  should only be used when overwrite problems are strongly suspected.
	  The advantage	of enabling memory validation is that a	guard zone
	  overwrite can	be detected on the first call to ckalloc or ckfree
	  after	the overwrite occurred,	rather than when the specific memory
	  with the overwritten guard zone(s) is	freed, which may occur long
	  after	the overwrite occurred.

     memory trace_on_at_malloc nnn
	  Enable memory	tracing	after nnn ckallocs have	been performed.	 For
	  example, if you enter	memory trace_on_at_malloc 100, after the 100th
	  call to ckalloc, memory trace	information will begin being displayed
	  for all allocations and frees.  Since	there can be a lot of memory
	  activity before a problem occurs, judicious use of this option can
	  reduce the slowdown caused by	tracing	(and the amount	of trace
	  information produced), if you	can identify a number of allocations
	  that occur before the	problem	sets in.  The current number of	memory
	  allocations that have	occured	since Tcl started is printed on	a
	  guard	zone failure.

     memory break_on_malloc nnn
	  After	the nnn	allocations have been performed, ckallocs output a
	  message to this effect and that it is	now attempting to enter	the C
	  debugger.  Tcl will then issue a SIGINT signal against itself.  If
	  you are running Tcl under a C	debugger, it should then enter the
	  debugger command mode.

     memory display file
	  Write	a list of all currently	allocated memory to the	specified


     Normally, Tcl compiled with memory	debugging enabled will make it easy to
     isolate a corruption problem.  Turning on memory validation with the
     memory command can	help isolate difficult problems.  If you suspect (or
     know) that	corruption is occurring	before the Tcl interpreter comes up
     far enough	for you	to issue commands, you can set MEM_VALIDATE define,
     recompile tclCkalloc.c and	rebuild	Tcl.  This will	enable memory
     validation	from the first call to ckalloc,	again, at a large performance

     If	you are	desperate and validating memory	on every call to ckalloc and
     ckfree isn't enough, you can explicitly call Tcl_ValidateAllMemory
     directly at any point.  It	takes a	char * and an int which	are normally
     the filename and line number of the caller, but they can actually be

									Page 4

Memory(3Tcl)							  Memory(3Tcl)

     anything you want.	 Remember to remove the	calls after you	find the

KEYWORDS    [Toc]    [Back]

     ckalloc, ckfree, free, memory, malloc

									Page 5

memory(3C)							    memory(3C)

NAME    [Toc]    [Back]

     memory: memccpy, memchr, memcmp, memcpy, memmove, memset -	memory

SYNOPSIS    [Toc]    [Back]

     #include <string.h>

     void *memccpy (void *s1, const void *s2, int c, size_t n);

     void *memchr (const void *s, int c, size_t	n);

     int memcmp	(const void *s1, const void *s2, size_t	n);

     void *memcpy (void	*s1, const void	*s2, size_t n);

     void *memmove (void *s1, const void *s2, size_t n);

     void *memset (void	*s, int	c, size_t n);

DESCRIPTION    [Toc]    [Back]

     These functions operate as	efficiently as possible	on memory areas
     (arrays of	bytes bounded by a count, not terminated by a null character).
     They do not check for the overflow	of any receiving memory	area.

     memccpy copies bytes from memory area s2 into s1, stopping	after the
     first occurrence of c (converted to an unsigned char) has been copied, or
     after n bytes have	been copied, whichever comes first.  It	returns	a
     pointer to	the byte after the copy	of c in	s1, or a null pointer if c was
     not found in the first n bytes of s2.

     memchr returns a pointer to the first occurrence of c (converted to an
     unsigned char) in the first n bytes (each interpreted as an unsigned
     char) of memory area s, or	a null pointer if c does not occur.

     memcmp compares its arguments, looking at the first n bytes (each
     interpreted as an unsigned	char), and returns an integer less than, equal
     to, or greater than 0, according as s1 is lexicographically less than,
     equal to, or greater than s2 when taken to	be unsigned characters.

     memcpy copies n bytes from	memory area s2 to s1.  It returns s1.

     memmove copies n bytes from memory	areas s2 to s1.	 Copying between
     objects that overlap will take place correctly.  It returns s1.

     memset sets the first n bytes in memory area s to the value of c
     (converted	to an unsigned char).  It returns s.

SEE ALSO    [Toc]    [Back]


									Page 1

memory(3C)							    memory(3C)

CAVEATS    [Toc]    [Back]

     For maximum portability, memmove should be	used when the memory areas
     indicated by s1 and s2 may	overlap, and memcpy used for faster copying
     between non-overlapping areas.  In	this implementation, however, memcpy
     is	an efficient copying algorithm which correctly handles overlapping

									PPPPaaaaggggeeee 2222
[ Back ]
 Similar pages
Name OS Title
realloc OpenBSD memory allocation and deallocation
malloc.conf OpenBSD memory allocation and deallocation
cfree OpenBSD memory allocation and deallocation
calloc OpenBSD memory allocation and deallocation
malloc OpenBSD memory allocation and deallocation
free OpenBSD memory allocation and deallocation
valloc OpenBSD aligned memory allocation function
malloc_ss IRIX SpeedShop memory allocation library
memory FreeBSD general memory allocation operations
malloc IRIX WorkShop memory allocation library
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service