Pointers play an important role in the C programming language. As the name suggests, they point to a byte in memory (like an address in a city). The C programming language gives you complete freedom in how to use the byte (and the bytes that follow it). Pointers are thus a very powerful feature of C. However, as the saying goes: “With great power comes great responsibility”, so they must be approached with care. The functions in this header are not very complex, they are just wrappers over some basic pointer functionality regarding pointer arithmetic and allocation (in memory or HDD/SSD).
Return a pointer to an element that is
increment elements ahead of
pointer, assuming each element has type of
type. For the type
codes, see Library data types (type.h).
When working with the
array elements of
gal_data_t, we are
actually dealing with
void * pointers. However, pointer arithmetic
does not apply to
void *, because the system does not know how many
bytes there are in each element to increment the pointer respectively. This
function will use the given
type to calculate where the incremented
element is located in memory.
Return the number of elements (in the given
later. For the type codes, see Library data types (type.h)).
clear, const char
*funcname, const char
Allocate an array of type
size elements in RAM (for the type codes, see Library data types (type.h)).
clear!=0, then the allocated space is set to zero (cleared).
This is effectively just a wrapper around C’s
calloc functions but takes Gnuastro’s integer type codes and will also abort with a clear error if there the allocation was not successful.
The number of allocated bytes is the value given to
size that is multiplied by the returned value of
gal_type_sizeof for the given type.
So if you want to allocate space for an array of strings you should pass the type
Otherwise, if you just want space for one string (for example, 6 bytes for
hello, including the string-termination character), you should set the type
When space cannot be allocated, this function will abort the program with a message containing the reason for the failure.
funcname (name of the function calling this function) and
varname (name of variable that needs this space) will be used in this error message if they are not
In most modern compilers, you can use the generic
__func__ variable for
In this way, you do not have to manually copy and paste the function name or worry about it changing later (
__func__ was standardized in C99).
quietmmap, const char
*funcname, const char
Allocate the given space either in RAM or in a memory-mapped file.
This function is just a high-level wrapper to
gal_pointer_allocate (to allocate in RAM) or
gal_pointer_mmap_allocate (to use a memory-mapped file).
For more on memory management in Gnuastro, please see Memory management.
The various arguments are more fully explained in the two functions above.
Allocate the necessary space to keep
size elements of type
type in HDD/SSD (a file, not in RAM).
For the type codes, see Library data types (type.h).
clear!=0, then the allocated space will also be cleared.
The allocation is done using C’s
The name of the file containing the allocated space is an allocated string that will be put in
Note that the kernel does not allow an infinite number of memory mappings to files. So it is not recommended to use this function with every allocation. The best-case scenario to use this function is for arrays that are very large and can fill up the RAM. Keep the smaller arrays in RAM, which is faster and can have a (theoretically) unlimited number of allocations.
When you are done with the dataset and do not need it anymore, do not use
free (the dataset is not in RAM).
Just delete the file (and the allocated space for the filename) with the commands below, or simply use
“Free” (actually delete) the memory-mapped file that is named
*mmapname, then free the string.
quietmmap is non-zero, then a warning will be printed for the user to know that the given file has been deleted.