ajmem.c

Function ajMemAlloc

Allocates memory using malloc, and fails with an error message if unsuccessful.

Synopsis

Prototype

void* ajMemAlloc (
      size_t nbytes,
      const char* file,
      ajint line,
      AjBool nofail
);

Type Name Read/Write Description

size_t nbytes Input Number of bytes required

const char* file Input Source file name, generated by a macro.

ajint line Input Source line number, generated by a macro.

AjBool nofail Input If true, return with a NULL pointer when unable to allocate.

void* RETURN Successfully allocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Type	Name	Read/Write	Description
size_t	nbytes	Input	Number of bytes required
const char*	file	Input	Source file name, generated by a macro.
ajint	line	Input	Source line number, generated by a macro.
AjBool	nofail	Input	If true, return with a NULL pointer when unable to allocate.
void*		RETURN	Successfully allocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Input

nbytes:	(Input)	Number of bytes required
file:	(Input)	Source file name, generated by a macro.
line:	(Input)	Source line number, generated by a macro.
nofail:	(Input)	If true, return with a NULL pointer when unable to allocate.

Returns

void*:

Successfully allocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Description

Allocates memory using malloc, and fails with an error message if unsuccessful.

Availability

In release 6.4.0

Function ajMemCalloc

Allocates memory using calloc for an array of elements, and fails with an error message if unsuccessful.

Synopsis

Prototype

void* ajMemCalloc (
      size_t count,
      size_t nbytes,
      const char* file,
      ajint line,
      AjBool nofail
);

Type Name Read/Write Description

size_t count Input Number of elements required

size_t nbytes Input Number of bytes required per element

const char* file Input Source file name, generated by a macro.

ajint line Input Source line number, generated by a macro.

AjBool nofail Input If true, return with a NULL pointer when unable to allocate.

void* RETURN Successfully allocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Type	Name	Read/Write	Description
size_t	count	Input	Number of elements required
size_t	nbytes	Input	Number of bytes required per element
const char*	file	Input	Source file name, generated by a macro.
ajint	line	Input	Source line number, generated by a macro.
AjBool	nofail	Input	If true, return with a NULL pointer when unable to allocate.
void*		RETURN	Successfully allocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Input

count:	(Input)	Number of elements required
nbytes:	(Input)	Number of bytes required per element
file:	(Input)	Source file name, generated by a macro.
line:	(Input)	Source line number, generated by a macro.
nofail:	(Input)	If true, return with a NULL pointer when unable to allocate.

Returns

void*:

Successfully allocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Description

Allocates memory using calloc for an array of elements, and fails with an error message if unsuccessful.

Availability

In release 6.4.0

Function ajMemCallocZero

Allocates memory using calloc for an array of elements, and fails with an error message if unsuccessful.

The memory is initialised to zero. This should be done by the standard calloc function. It is explicitly done here to make sure.

Synopsis

Prototype

void* ajMemCallocZero (
      size_t count,
      size_t nbytes,
      const char* file,
      ajint line,
      AjBool nofail
);

Type Name Read/Write Description

size_t count Input Number of elements required

size_t nbytes Input Number of bytes required

const char* file Input Source file name, generated by a macro.

ajint line Input Source line number, generated by a macro.

AjBool nofail Input If true, return with a NULL pointer when unable to allocate.

void* RETURN Successfully allocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Type	Name	Read/Write	Description
size_t	count	Input	Number of elements required
size_t	nbytes	Input	Number of bytes required
const char*	file	Input	Source file name, generated by a macro.
ajint	line	Input	Source line number, generated by a macro.
AjBool	nofail	Input	If true, return with a NULL pointer when unable to allocate.
void*		RETURN	Successfully allocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Input

count:	(Input)	Number of elements required
nbytes:	(Input)	Number of bytes required
file:	(Input)	Source file name, generated by a macro.
line:	(Input)	Source line number, generated by a macro.
nofail:	(Input)	If true, return with a NULL pointer when unable to allocate.

Returns

void*:

Successfully allocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Description

Allocates memory using calloc for an array of elements, and fails with an error message if unsuccessful.

The memory is initialised to zero. This should be done by the standard calloc function. It is explicitly done here to make sure.

Availability

In release 6.4.0

Function ajMemSetZero

Zeroes memory for an array of elements,

Synopsis

Prototype

void ajMemSetZero (
      void* ptr,
      size_t count,
      size_t nbytes
);

Type Name Read/Write Description

void* ptr Modify Pointer to memory previously allocated with 'malloc'

size_t count Input Number of elements required

size_t nbytes Input Number of bytes required

void RETURN

Type	Name	Read/Write	Description
void*	ptr	Modify	Pointer to memory previously allocated with 'malloc'
size_t	count	Input	Number of elements required
size_t	nbytes	Input	Number of bytes required
void		RETURN

Input

count:	(Input)	Number of elements required
nbytes:	(Input)	Number of bytes required

Input & Output

ptr:

(Modify)

Pointer to memory previously allocated with 'malloc'

Returns

void:

No return value

Description

Zeroes memory for an array of elements,

Availability

In release 6.4.0

Function ajMemFree

Frees memory using 'free' and zeroes the pointer. Ignores NULL (uninitialised) pointers.

Synopsis

Prototype

void ajMemFree (
      void** ptr
);

Input & Output

Type Name Read/Write Description

void** ptr Modify Pointer to memory previously allocated with 'malloc'

ptr: (Modify) Pointer to memory previously allocated with 'malloc'

Type	Name	Read/Write	Description
void**	ptr	Modify	Pointer to memory previously allocated with 'malloc'

Description

Frees memory using 'free' and zeroes the pointer. Ignores NULL (uninitialised) pointers.

Availability

In release 6.4.0

Function ajMemResize

Resizes previously allocated memory, and ensures data is copied to the new location if it is moved.

If the pointer is new then new memory is allocated automatically.

The C run-time library function realloc does preserve existing values but does not initialise any memory after the old contents.

Synopsis

Prototype

void* ajMemResize (
      void* ptr,
      size_t nbytes,
      const char* file,
      ajint line,
      AjBool nofail
);

void*ptrModifyPointer to memory previously allocated with 'malloc' size_tnbytesInputNumber of bytes required const char*fileInputSource file name, generated by a macro. ajintlineInputSource line number, generated by a macro. AjBoolnofailInputIf true, return with a NULL pointer when unable to allocate. void* RETURNSuccessfully reallocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Input

nbytes:	(Input)	Number of bytes required
file:	(Input)	Source file name, generated by a macro.
line:	(Input)	Source line number, generated by a macro.
nofail:	(Input)	If true, return with a NULL pointer when unable to allocate.

Input & Output

ptr:

(Modify)

Pointer to memory previously allocated with 'malloc'

Returns

void*:

Successfully reallocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Description

Resizes previously allocated memory, and ensures data is copied to the new location if it is moved.

If the pointer is new then new memory is allocated automatically.

The C run-time library function realloc does preserve existing values but does not initialise any memory after the old contents.

Availability

In release 6.4.0

Function ajMemResizeZero

Resizes previously allocated memory, and ensures data is copied to the new location if it is moved.

If the pointer is new then new memory is allocated automatically.

Memory beyond the previous contents is initialised to zero

The C run-time library function realloc does preserves existing values but does not initialise any memory after the old contents. This is why this function needs to be told what the old size was.

Synopsis

Prototype

void* ajMemResizeZero (
      void* ptr,
      size_t oldbytes,
      size_t nbytes,
      const char* file,
      ajint line,
      AjBool nofail
);

Type Name Read/Write Description

void* ptr Modify Pointer to memory previously allocated with 'malloc'

size_t oldbytes Input Number of bytes required

size_t nbytes Input Number of bytes required

const char* file Input Source file name, generated by a macro.

ajint line Input Source line number, generated by a macro.

AjBool nofail Input If true, return with a NULL pointer when unable to allocate.

void* RETURN Successfully reallocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Type	Name	Read/Write	Description
void*	ptr	Modify	Pointer to memory previously allocated with 'malloc'
size_t	oldbytes	Input	Number of bytes required
size_t	nbytes	Input	Number of bytes required
const char*	file	Input	Source file name, generated by a macro.
ajint	line	Input	Source line number, generated by a macro.
AjBool	nofail	Input	If true, return with a NULL pointer when unable to allocate.
void*		RETURN	Successfully reallocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Input

oldbytes:	(Input)	Number of bytes required
nbytes:	(Input)	Number of bytes required
file:	(Input)	Source file name, generated by a macro.
line:	(Input)	Source line number, generated by a macro.
nofail:	(Input)	If true, return with a NULL pointer when unable to allocate.

Input & Output

ptr:

(Modify)

Pointer to memory previously allocated with 'malloc'

Returns

void*:

Successfully reallocated memory, or NULL on failure. Normal behaviour is to raise an exception and fail, or if running with Java, to print to standard error and exit.

Description

Resizes previously allocated memory, and ensures data is copied to the new location if it is moved.

If the pointer is new then new memory is allocated automatically.

Memory beyond the previous contents is initialised to zero

The C run-time library function realloc does preserves existing values but does not initialise any memory after the old contents. This is why this function needs to be told what the old size was.

Availability

In release 6.4.0

Function ajMemArrB

Creates an AjBool array. Use AJFREE to free the memory when no longer needed.

Synopsis

Prototype

ajint* ajMemArrB (
      size_t size
);

Type Name Read/Write Description

size_t size Input Number of array elements.

ajint* RETURN Newly allocated array.

Type	Name	Read/Write	Description
size_t	size	Input	Number of array elements.
ajint*		RETURN	Newly allocated array.

Input

size:

(Input)

Number of array elements.

Returns

ajint*:

Newly allocated array.

Description

Creates an AjBool array. Use AJFREE to free the memory when no longer needed.

Availability

In release 6.4.0

Function ajMemArrI

Creates an integer array. Use AJFREE to free the memory when no longer needed.

Synopsis

Prototype

ajint* ajMemArrI (
      size_t size
);

Type Name Read/Write Description

size_t size Input Number of array elements.

ajint* RETURN Newly allocated array.

Type	Name	Read/Write	Description
size_t	size	Input	Number of array elements.
ajint*		RETURN	Newly allocated array.

Input

size:

(Input)

Number of array elements.

Returns

ajint*:

Newly allocated array.

Description

Creates an integer array. Use AJFREE to free the memory when no longer needed.

Availability

In release 6.4.0

Function ajMemArrF

Creates a float array. Use AJFREE to free the memory when no longer needed.

Synopsis

Prototype

float* ajMemArrF (
      size_t size
);

Type Name Read/Write Description

size_t size Input Number of array elements.

float* RETURN Newly allocated array.

Type	Name	Read/Write	Description
size_t	size	Input	Number of array elements.
float*		RETURN	Newly allocated array.

Input

size:

(Input)

Number of array elements.

Returns

float*:

Newly allocated array.

Description

Creates a float array. Use AJFREE to free the memory when no longer needed.

Availability

In release 6.4.0

Function ajMemStat

Prints a summary of memory usage with debug calls

Synopsis

Prototype

void ajMemStat (
      const char* title
);

Type Name Read/Write Description

const char* title Input Title for this summary

void RETURN

Type	Name	Read/Write	Description
const char*	title	Input	Title for this summary
void		RETURN

Input

title:

(Input)

Title for this summary

Returns

void:

No return value

Description

Prints a summary of memory usage with debug calls

Availability

In release 6.4.0

Function ajMemExit

Prints a summary of memory usage with debug calls

Synopsis

Prototype

void ajMemExit (
      void
);

Type Name Read/Write Description

void RETURN

Type	Name	Read/Write	Description
void		RETURN

Returns

void:

No return value

Description

Prints a summary of memory usage with debug calls

Availability

In release 6.4.0

Function ajMemCheck

Prints a message appropriate to the memcheck status

Synopsis

Prototype

void ajMemCheck (
      int istat
);

Type Name Read/Write Description

int istat Input Enumerated value from mprobe

void RETURN

Type	Name	Read/Write	Description
int	istat	Input	Enumerated value from mprobe
void		RETURN

Input

istat:

(Input)

Enumerated value from mprobe

Returns

void:

No return value

Description

Prints a message appropriate to the memcheck status

Availability

In release 6.4.0

Function ajMemCheckSetLimit

Prints a message appropriate to the memcheck status

Synopsis

Prototype

void ajMemCheckSetLimit (
      ajint maxfail
);

Type Name Read/Write Description

ajint maxfail Input Maximum failures allowed

void RETURN

Type	Name	Read/Write	Description
ajint	maxfail	Input	Maximum failures allowed
void		RETURN

Input

maxfail:

(Input)

Maximum failures allowed

Returns

void:

No return value

Description

Prints a message appropriate to the memcheck status

Availability

In release 6.4.0

Function ajMemProbe

Probes a memory location for possible errors

Synopsis

Prototype

void ajMemProbe (
      void* ptr,
      const char* file,
      ajint line
);

Type Name Read/Write Description

void* ptr Modify Pointer to memory previously allocated with 'malloc'

const char* file Input Source file name, generated by a macro.

ajint line Input Source line number, generated by a macro.

void RETURN

Type	Name	Read/Write	Description
void*	ptr	Modify	Pointer to memory previously allocated with 'malloc'
const char*	file	Input	Source file name, generated by a macro.
ajint	line	Input	Source line number, generated by a macro.
void		RETURN

Input

file:	(Input)	Source file name, generated by a macro.
line:	(Input)	Source line number, generated by a macro.

Input & Output

ptr:

(Modify)

Pointer to memory previously allocated with 'malloc'

Returns

void:

No return value

Description

Probes a memory location for possible errors

Availability

In release 6.4.0

ajmem.c

Synopsis

Prototype

Input

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Input & Output

Description

See Also

Availability

Synopsis

Prototype

Input

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

See Also

Availability