icalmemory.h File Reference

Common memory management routines. More...

Go to the source code of this file.

Functions
void	icalmemory_add_tmp_buffer (void *buf)
	Adds an externally allocated buffer to the ring.
void	icalmemory_append_char (char **buf, char **pos, size_t *buf_size, char ch)
	Appends a character to a buffer.
void	icalmemory_append_decoded_string (char **buf, char **pos, size_t *buf_size, const char *string)
void	icalmemory_append_encoded_string (char **buf, char **pos, size_t *buf_size, const char *string)
void	icalmemory_append_string (char **buf, char **pos, size_t *buf_size, const char *string)
	Appends a string to a buffer.
void	icalmemory_free_buffer (void *buf)
	Releases a buffer.
void	icalmemory_free_ring (void)
	Frees all memory used in the ring.
void	icalmemory_get_mem_alloc_funcs (icalmemory_malloc_f *f_malloc, icalmemory_realloc_f *f_realloc, icalmemory_free_f *f_free)
	Returns the functions used for memory management.
void *	icalmemory_new_buffer (size_t size)
	Creates new buffer with the specified size.
void *	icalmemory_resize_buffer (void *buf, size_t size)
	Resizes a buffer created with icalmemory_new_buffer().
void	icalmemory_set_mem_alloc_funcs (icalmemory_malloc_f f_malloc, icalmemory_realloc_f f_realloc, icalmemory_free_f f_free)
	Configures the functions to use for memory management.
char *	icalmemory_strdup (const char *s)
	Creates a duplicate of a string.
void *	icalmemory_tmp_buffer (size_t size)
	Creates a new temporary buffer on the ring and returns it.
char *	icalmemory_tmp_copy (const char *str)
	Creates a copy of the given string, stored on the ring buffer, and returns it.

Detailed Description

Common memory management routines.

libical often passes strings back to the caller. To make these interfaces simple, I did not want the caller to have to pass in a memory buffer, but having libical pass out newly allocated memory makes it difficult to de-allocate the memory.

The ring buffer in this scheme makes it possible for libical to pass out references to memory which the caller does not own, and be able to de-allocate the memory later. The ring allows libical to have several buffers active simultaneously, which is handy when creating string representations of components. Methods for working with these temporary buffers are marked with icalmemory_tmp_*().

Other memory management routines include wrappers around the system management routines like icalmemory_new_buffer() and icalmemory_free_buffer() as well as routines to work with strings, like icalmemory_append_string().

Definition in file icalmemory.h.

Function Documentation

icalmemory_add_tmp_buffer()

void icalmemory_add_tmp_buffer

(

void *

buf

)

Adds an externally allocated buffer to the ring.

Parameters

buf	The externally allocated buffer to add to the ring

Adds an externally allocated buffer to the ring. This ensures that libical will free() the buffer automatically, either after BUFFER_RING_SIZE other buffers have been created or added, or after icalmemory_free_ring() has been called. Note that freeing the buffers is done using the icalmemory_free_buffer() function, which by default is a wrapper around stdlib's free() function. However, if the memory management functions are customized by the user, the user must make sure to only pass in buffers that have been allocated in a compatible manner.

Error handling

No error is raised if buf is NULL.

Ownership

After adding buf to the ring, it becomes owned by icalmemory and must not be free()d manually anymore, it leads to a double-free() when icalmemory reclaims the memory.

Usage

char *buf = calloc(256, sizeof(char));
 
icalmemory_add_tmp_buffer(buf);

Definition at line 156 of file icalmemory.c.

icalmemory_append_char()

void icalmemory_append_char	(	char **	buf,
		char **	pos,
		size_t *	buf_size,
		char	ch )

Appends a character to a buffer.

Parameters

buf	The buffer to append the character to.
pos	The position to append the character at.
buf_size	The size of the buffer (will be changed if buffer is reallocated)
ch	The character to append to the buffer.

Warning

This method may not be used for temporary buffers (buffers allocated with icalmemory_tmp_buffer() and related functions)!

Error handling

Sets icalerrno to ICAL_BADARG_ERROR if buf, *buf, pos, * pos, or buf_size NULL.

This method will copy the character ch and a ‘’\0' character after it to the buffer @a buf starting at position @a pos, reallocing @a buf if it is too small. @a buf_size is the size of @a buf and will be changed if @a buf is reallocated. @a pos will point to the new terminating '\0'` character buf.

Example

// creates a new buffer
int buffer_len = 15;
char *buffer = icalmemory_new_buffer(buffer_len);
strcpy(buffer, "My number is: ");
 
// append a char to the buffer
int buffer_end = strlen(buffer);
char *buffer_end_pos = buffer[buffer_str_end];
icalmemory_append_char(&buffer, &buffer_end_pos, &buffer_len, '7');
 
// print string
printf("%s\n", buffer);
 
// release memory
icalmemory_free_buffer(buffer);

Definition at line 404 of file icalmemory.c.

icalmemory_append_decoded_string()

void icalmemory_append_decoded_string	(	char **	buf,
		char **	pos,
		size_t *	buf_size,
		const char *	string )

Decodes a string as TEXT value and then appends it to the buffer.

Only use on normally allocated memory, or on buffers created from icalmemory_new_buffer, never with buffers created by icalmemory_tmp_buffer. If icalmemory_append_decoded_string has to resize a buffer on the ring, the ring will loose track of it and you will have memory problems

Parameters

buf	a pointer to a char string buffer to be appended. The associated memory should not be part of the temporary memory managed by the library.
pos	the position in buf in which the new string to be appended
buf_size	the size of the buffer before appended
string	a pointer to char string to be allocated

Definition at line 519 of file icalmemory.c.

icalmemory_append_encoded_string()

void icalmemory_append_encoded_string	(	char **	buf,
		char **	pos,
		size_t *	buf_size,
		const char *	string )

Encodes a string per RFC 6868 and then appends it to the specified char string buffer.

This function filters out the characters not permitted by the RFC. paramtext = *SAFE-CHAR quoted-string= DQUOTE *QSAFE-CHAR DQUOTE

Only use on normally allocated memory, or on buffers created from icalmemory_new_buffer, never with buffers created by icalmemory_tmp_buffer. If icalmemory_append_encoded_string has to resize a buffer on the ring, the ring will loose track of it and you will have memory problems.

Parameters

buf	a pointer to a char string buffer to be appended. The associated memory should not be part of the temporary memory managed by the library.
pos	the position in buf in which the new string to be appended
buf_size	the size of the buffer before appended
string	a pointer to char string to be allocated

Definition at line 476 of file icalmemory.c.

icalmemory_append_string()

void icalmemory_append_string	(	char **	buf,
		char **	pos,
		size_t *	buf_size,
		const char *	string )

Appends a string to a buffer.

Parameters

buf	The buffer to append the string to.
pos	The position to append the string at.
buf_size	The size of the buffer (will be changed if buffer is reallocated)
string	The string to append to the buffer.

Warning

This method may not be used for temporary buffers (buffers allocated with icalmemory_tmp_buffer() and related functions)!

Error handling

Sets icalerrno to ICAL_BADARG_ERROR if buf, *buf, pos, * pos, buf_size or string are NULL.

This method will copy the string string to the buffer buf starting at position pos, reallocing buf if it is too small. buf_size is the size of buf and will be changed if buf is reallocated. pos will point to the last byte of the new string in buf, usually a ‘’\0'`

Example

// creates a new buffer
int buffer_len = 15;
char *buffer = icalmemory_new_buffer(buffer_len);
strcpy(buffer, "My name is: ");
 
// append a string to the buffer
int buffer_end = strlen(buffer);
char *buffer_end_pos = buffer[buffer_str_end];
icalmemory_append_string(&buffer, &buffer_end_pos, &buffer_len, "John Doe");
 
// print string
printf("%s\n", buffer);
 
// release memory
icalmemory_free_buffer(buffer);

Definition at line 363 of file icalmemory.c.

icalmemory_free_buffer()

void icalmemory_free_buffer

(

void *

buf

)

Releases a buffer.

Parameters

buf	The buffer to release

See also

icalmemory_new_buffer()

Releases the memory of the buffer.

By default this function delegates to stdlib's free() but the used function can be configured via icalmemory_set_mem_alloc_funcs().

Definition at line 353 of file icalmemory.c.

icalmemory_free_ring()

void icalmemory_free_ring

(

void

)

Frees all memory used in the ring.

Frees all memory used in the ring. If PTHREAD is used or thread-local mode is configured, the ring buffer is allocated on a per-thread basis, meaning that if all rings are to be released, it must be called once in every thread.

Usage

c
  void *buf = icalmemory_tmp_buffer(256);
 
  // use buf
 
  // release buf and all other memory in the ring buffer
  icalmemory_free_ring();

Definition at line 202 of file icalmemory.c.

icalmemory_get_mem_alloc_funcs()

void icalmemory_get_mem_alloc_funcs	(	icalmemory_malloc_f *	f_malloc,
		icalmemory_realloc_f *	f_realloc,
		icalmemory_free_f *	f_free )

Returns the functions used for memory management.

Parameters

f_malloc	A pointer to the function to use for memory allocation.
f_realloc	A pointer to the function to use for memory reallocation.
f_free	A pointer to the function to use for memory deallocation.

Retrieves the functions used by the library for memory management.

Since

4.0

Definition at line 293 of file icalmemory.c.

icalmemory_new_buffer()

void * icalmemory_new_buffer

(

size_t

size

)

Creates new buffer with the specified size.

Parameters

size	The size of the buffer that is to be created.

Returns

A pointer to the newly-created buffer.

See also

icalmemory_free_buffer()

Error handling

If there is a problem allocating memory, it sets icalerrno to ICAL_NEWFAILED_ERROR and returns NULL.

Ownership

Buffers created with this method are owned by the caller. They must be released with the icalmemory_free_buffer() method.

This creates a new (non-temporary) buffer of the specified size. All buffers returned by this method are zeroed-out.

By default this function delegates to stdlib's malloc() but the used function can be changed via icalmemory_set_mem_alloc_funcs().

Usage

// create buffer
char *buffer = icalmemory_new_buffer(50);
 
// fill buffer
strcpy(buffer, "some data");
 
// release buffer
icalmemory_free_buffer(buffer);

Definition at line 313 of file icalmemory.c.

icalmemory_resize_buffer()

void * icalmemory_resize_buffer	(	void *	buf,
		size_t	size )

Resizes a buffer created with icalmemory_new_buffer().

Parameters

buf	The buffer to be resized.
size	The new size of the buffer.

Returns

The new, resized buffer.

See also

icalmemory_new_buffer()

Warning

This method may not be used for temporary buffers (buffers allocated with icalmemory_tmp_buffer() and related functions)!

Error handling

If there is a problem while reallocating the buffer, the method sets icalerrno to ICAL_NEWFAILED_ERROR and returns NULL.

Ownership

The returned buffer is owned by the caller and needs to be released with the appropriate icalmemory_free_buffer() method. The old buffer, buf, can not be used anymore after calling this method.

By default this function delegates to stdlib's realloc() but the used function can be configured via icalmemory_set_mem_alloc_funcs().

Usage

// create new buffer
char *buffer = icalmemory_new_buffer(10);
 
// fill buffer
strcpy(buffer, "some data");
 
// expand buffer
buffer = icalmemory_resize_buffer(buffer, 20);
 
// fill with more data
strcpy(buffer, "a lot more data");
 
// release
icalmemory_free_buffer(buffer);

Definition at line 334 of file icalmemory.c.

icalmemory_set_mem_alloc_funcs()

void icalmemory_set_mem_alloc_funcs	(	icalmemory_malloc_f	f_malloc,
		icalmemory_realloc_f	f_realloc,
		icalmemory_free_f	f_free )

Configures the functions to use for memory management.

Parameters

f_malloc	The function to use for memory allocation.
f_realloc	The function to use for memory reallocation.
f_free	The function to use for memory deallocation.

This function configures the library to use the specified functions for memory management. By default the standard system memory management functions malloc(), realloc() and free() are used.

Note: The memory management functions configured via this functions are used throughout the core libical component but not within other components like libicalvcal.

Since

4.0

Definition at line 284 of file icalmemory.c.

icalmemory_strdup()

char * icalmemory_strdup

(

const char *

s

)

Creates a duplicate of a string.

Parameters

s	The string to duplicate.

Returns

A pointer to a string containing the same data as s

Error handling

The string s must not be NULL, otherwise depending on the libc used, it might lead to undefined behaviour (read: segfaults).

Ownership

The returned string is owned by the caller and needs to be released with the icalmemory_free_buffer() method.

Replaces strdup(). The function uses icalmemory_new_buffer() for memory allocation. It also helps trapping calls to strdup() and solves the problem that in -ansi, gcc on Red Hat claims that strdup() is undeclared.

Usage

const char *my_str = "LibIcal";
char *dup = icalmemory_strdup(my_str);
printf("%s\n", dup);
icalmemory_free_buffer(dup);

Definition at line 240 of file icalmemory.c.

icalmemory_tmp_buffer()

void * icalmemory_tmp_buffer

(

size_t

size

)

Creates a new temporary buffer on the ring and returns it.

Parameters

size	How big (in bytes) the buffer should be

Returns

A pointer to the newly created buffer on the ring

Creates a temporary buffer on the ring. Regardless of what size you specify, the buffer will always be at least MIN_BUFFER_SIZE big, and it will be zeroed out.

Error handling

If there is a problem allocating memory for the buffer, it sets icalerrno to ICAL_NEWFAILED_ERROR and returns NULL.

Ownership

The returned buffer is owned by icalmemory. It must not be freed by the caller and the returned memory will be automatically reclaimed as more items are added to the ring buffer.

Usage

char *str = icalmemory_tmp_buffer(256);
strcpy(str, "some data");
 
// use str

Definition at line 180 of file icalmemory.c.

icalmemory_tmp_copy()

char * icalmemory_tmp_copy

(

const char *

str

)

Creates a copy of the given string, stored on the ring buffer, and returns it.

Parameters

str	The string to copy

Returns

A copy of str, which has been placed on the ring buffer for automatic reclamation.

Error handling

The passed string str must not be NULL, otherwise a segfault might ensue, since the routine calls strlen() on it.

Ownership

The returned string is owned by icalmemory. It must not be freed by the caller, and it will be automatically reclaimed as more items are added to the buffer.

Usage

const char *str = "Example string";
char *tmp_copy = icalmemory_tmp_copy(str);

Definition at line 220 of file icalmemory.c.