chunk.h

/*
 * Defines for low level memory management routines
 *
 * Copyright 2020 by Gray Watson
 *
 * This file is part of the dmalloc package.
 *
 * Permission to use, copy, modify, and distribute this software for
 * any purpose and without fee is hereby granted, provided that the
 * above copyright notice and this permission notice appear in all
 * copies, and that the name of Gray Watson not be used in advertising
 * or publicity pertaining to distribution of the document or software
 * without specific, written prior permission.
 *
 * Gray Watson makes no representations about the suitability of the
 * software described herein for any purpose.  It is provided "as is"
 * without express or implied warranty.
 *
 * The author may be contacted via https://dmalloc.com/
 */

#ifndef __CHUNK_H__
#define __CHUNK_H__

/*<<<<<<<<<<  The below prototypes are auto-generated by fillproto */

/* limit in how much memory we are allowed to allocate */
extern
unsigned long		_dmalloc_memory_limit;

/* total number of bytes that the heap has allocated */
extern
unsigned long		_dmalloc_alloc_total;

/*
 * int _dmalloc_chunk_startup
 * 
 * Startup the low level malloc routines.
 *
 * Returns 1 on success or 0 on failure.
 */
extern
int	_dmalloc_chunk_startup(void);

/*
 * char *_dmalloc_chunk_desc_pnt
 *
 * Write into a buffer a pointer description with file and line-number.
 *
 * Returns a pointer to buffer 1st argument.
 *
 * ARGUMENTS:
 *
 * buf <-> Passed in buffer which will be filled with a description of
 * the pointer.
 *
 * buf_size -> Size of the buffer in bytes.
 *
 * file -> File name, return address, or NULL.
 *
 * line -> Line number or 0.
 */
extern
char	*_dmalloc_chunk_desc_pnt(char *buf, const int buf_size,
				 const char *file, const unsigned int line);

/*
 * int _dmalloc_chunk_read_info
 *
 * Return some information associated with a pointer.
 *
 * Returns 1 if the pointer is okay or 0 if a problem with pointer
 *
 * ARGUMENTS:
 *
 * user_pnt -> Pointer we are checking.
 *
 * where <- Where the check is being made from.
 *
 * user_size_p <- Pointer to an unsigned int which, if not NULL, will
 * be set to the size of bytes that the user requested.
 *
 * alloc_size_p <- Pointer to an unsigned int which, if not NULL, will
 * be set to the total given size of bytes including block overhead.
 *
 * file_p <- Pointer to a character pointer which, if not NULL, will
 * be set to the file where the pointer was allocated.
 *
 * line_p <- Pointer to a character pointer which, if not NULL, will
 * be set to the line-number where the pointer was allocated.
 *
 * ret_attr_p <- Pointer to a void pointer, if not NULL, will be set
 * to the return-address where the pointer was allocated.
 *
 * seen_cp <- Pointer to an unsigned long which, if not NULL, will be
 * set to the number of times the pointer has been "seen".
 *
 * used_p <- Pointer to an unsigned long which, if not NULL, will be
 * set to the last time the pointer was "used".
 *
 * valloc_bp <- Pointer to an integer which, if not NULL, will be set
 * to 1 if the pointer was allocated with valloc otherwise 0.
 *
 * fence_bp <- Pointer to an integer which, if not NULL, will be set
 * to 1 if the pointer has the fence bit set otherwise 0.
 */
extern
int	_dmalloc_chunk_read_info(const void *user_pnt, const char *where,
				 unsigned int *user_size_p,
				 unsigned int *alloc_size_p, char **file_p,
				 unsigned int *line_p, void **ret_attr_p,
				 unsigned long **seen_cp,
				 unsigned long *used_p, int *valloc_bp,
				 int *fence_bp);

/*
 * int _dmalloc_chunk_heap_check
 *
 * Run extensive tests on the entire heap.
 *
 * Returns 1 if the heap is okay or 0 if a problem was detected
 */
extern
int	_dmalloc_chunk_heap_check(void);

/*
 * int _dmalloc_chunk_pnt_check
 *
 * Run extensive tests on a pointer.
 *
 * Returns 1 if the pointer is okay or 0 if not
 *
 * ARGUMENTS:
 *
 * func -> Function string which is checking the pointer.
 *
 * user_pnt -> Pointer we are checking.
 *
 * exact_b -> Set to 1 to find the pointer specifically.  Otherwise we
 * can find the pointer inside of an allocation.
 *
 * strlen_b -> Make sure that pnt can hold at least a strlen + 1
 * bytes.  If 0 then ignore.
 *
 * min_size -> Make sure that pnt can hold at least that many bytes.
 * If 0 then ignore.
 */
extern
int	_dmalloc_chunk_pnt_check(const char *func, const void *user_pnt,
				 const int exact_b, const int strlen_b,
				 const int min_size);

/*
 * void *_dmalloc_chunk_malloc
 *
 * Allocate a chunk of memory.
 *
 * Returns a valid pointer on success or NULL on failure.
 *
 * ARGUMENTS:
 *
 * file -> File-name or return-address location of the allocation.
 *
 * line -> Line-number location of the allocation.
 *
 * size -> Number of bytes to allocate.
 *
 * func_id -> Calling function-id as defined in dmalloc.h.
 *
 * alignment -> If greater than 0 then try to align the returned
 * block.
 */
extern
void	*_dmalloc_chunk_malloc(const char *file, const unsigned int line,
			       const unsigned long size, const int func_id,
			       const unsigned int alignment);

/*
 * int _dmalloc_chunk_free
 *
 * Free a user pointer from the heap.
 *
 * Returns FREE_NOERROR on success or FREE_ERROR on failure
 *
 * ARGUMENTS:
 *
 * file -> File-name or return-address location of the allocation.
 *
 * line -> Line-number location of the allocation.
 *
 * user_pnt -> Pointer we are freeing.
 *
 * func_id -> Function ID
 */
extern
int	_dmalloc_chunk_free(const char *file, const unsigned int line,
			    void *user_pnt, const int func_id);

/*
 * void *_dmalloc_chunk_realloc
 *
 * Re-allocate a chunk of memory either shrinking or expanding it.
 *
 * Returns a valid pointer on success of NULL on failure.
 *
 * ARGUMENTS:
 *
 * file -> File-name or return-address location of the allocation.
 *
 * line -> Line-number location of the allocation.
 *
 * old_user_pnt -> Old user pointer that we are reallocating.
 *
 * new_size -> New-size to change the pointer.
 *
 * func_id -> Calling function-id as defined in dmalloc.h.
 */
extern
void	*_dmalloc_chunk_realloc(const char *file, const unsigned int line,
				void *old_user_pnt,
				const unsigned long new_size,
				const int func_id);

/*
 * void _dmalloc_chunk_log_stats
 *
 * Log general statistics from the heap to the logfile.
 */
extern
void	_dmalloc_chunk_log_stats(void);

/*
 * void _dmalloc_chunk_log_changed
 *
 * Log the pointers that has changed since a pointer in time.
 *
 * ARGUMENTS:
 *
 * mark -> Dmalloc counter used to mark a specific time so that
 * servers can check on the changed pointers.
 *
 * log_non_free_b -> If set to 1 then log the new not-freed
 * (i.e. used) pointers.
 *
 * log_free_b -> If set to 1 then log the new freed pointers.
 *
 * details_b -> If set to 1 then dump the individual pointer entries
 * instead of just the summary.
 */
extern
void	_dmalloc_chunk_log_changed(const unsigned long mark,
				   const int log_not_freed_b,
				   const int log_freed_b, const int details_b);

/*
 * unsigned long _dmalloc_chunk_count_changed
 *
 * Return the pointers that has changed since a pointer in time.
 *
 * Returns the number of bytes changed since mark.
 *
 * ARGUMENTS:
 *
 * mark -> Dmalloc counter used to mark a specific time so that
 * servers can check on the changed pointers.
 *
 * count_non_free_b -> If set to 1 then count the new not-freed
 * (i.e. used) pointers.
 *
 * count_free_b -> If set to 1 then count the new freed pointers.
 */
extern
unsigned long	_dmalloc_chunk_count_changed(const unsigned long mark,
					     const int count_not_freed_b,
					     const int count_freed_b);

/*
 * void _dmalloc_chunk_get_stats
 *
 * Return a number of statistics about the current heap.
 *
 * ARGUMENTS:
 *
 * heap_low_p <- Pointer to pointer which, if not 0L, will be set to
 * the low address in the heap.
 *
 * heap_high_p <- Pointer to pointer which, if not 0L, will be set to
 * the high address in the heap.
 *
 * total_space_p <- Pointer to an unsigned long which, if not 0L, will
 * be set to the total space managed by the library including user
 * space, administrative space, and overhead.
 *
 * user_space_p <- Pointer to an unsigned long which, if not 0L, will
 * be set to the space given to the user process (allocated and free).
 *
 * current_allocated_p <- Pointer to an unsigned long which, if not
 * 0L, will be set to the current allocated space given to the user
 * process.
 *
 * current_pnt_np <- Pointer to an unsigned long which, if not 0L,
 * will be set to the current number of pointers allocated by the user
 * process.
 *
 * max_allocated_p <- Pointer to an unsigned long which, if not 0L,
 * will be set to the maximum allocated space given to the user
 * process.
 *
 * max_pnt_np <- Pointer to an unsigned long which, if not 0L, will be
 * set to the maximum number of pointers allocated by the user
 * process.
 *
 * max_one_p <- Pointer to an unsigned long which, if not 0L, will be
 * set to the maximum allocated with 1 call by the user process.
 */
extern
void	_dmalloc_chunk_get_stats(void **heap_low_p, void **heap_high_p,
				 unsigned long *total_space_p,
				 unsigned long *user_space_p,
				 unsigned long *current_allocated_p,
				 unsigned long *current_pnt_np,
				 unsigned long *max_allocated_p,
				 unsigned long *max_pnt_np,
				 unsigned long *max_one_p);

/*<<<<<<<<<<   This is end of the auto-generated output from fillproto. */

#endif /* ! __CHUNK_H__ */