icalmemory.c File Reference

Data Structures
struct	buffer_ring

Macros
#define	BUFFER_RING_SIZE   2500
	Determines the size of the ring buffer used for keeping track of temporary buffers.
#define	MIN_BUFFER_SIZE   200
	Determines the minimal size of buffers in the ring that are created with icalmemory_tmp_buffer().

Functions
void	icalmemory_add_tmp_buffer (void *buf)
	Add an externally allocated buffer to the ring. More...
void	icalmemory_append_char (char **buf, char **pos, size_t *buf_size, char ch)
	Append a character to a buffer. More...
void	icalmemory_append_string (char **buf, char **pos, size_t *buf_size, const char *string)
	Append a string to a buffer. More...
void	icalmemory_free_buffer (void *buf)
	Releases a buffer. More...
void	icalmemory_free_ring ()
	Free all memory used in the ring. More...
void *	icalmemory_new_buffer (size_t size)
	Creates new buffer with the specified size. More...
void *	icalmemory_resize_buffer (void *buf, size_t size)
	Resizes a buffer created with icalmemory_new_buffer(). More...
char *	icalmemory_strdup (const char *s)
	Create a duplicate of a string. More...
void *	icalmemory_tmp_buffer (size_t size)
	Creates a new temporary buffer on the ring and returns it. More...
char *	icalmemory_tmp_copy (const char *str)
	Creates a copy of the given string, stored on the ring buffer, and returns it. More...

Function Documentation

icalmemory_add_tmp_buffer()

void icalmemory_add_tmp_buffer

(

void *

buf

)

Add 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.

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);

icalmemory_append_char()

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

Append 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. 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 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 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);

icalmemory_append_string()

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

Append 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. 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);

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.

icalmemory_free_ring()

void icalmemory_free_ring

(

void

)

Free all memory used in the ring.

Frees all memory used in the ring. Depending on if ::HAVE_PTHREAD is set or not, 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

void *buf = icalmemory_tmp_buffer(256);

// use buf

// release buf and all other memory in the ring buffer
icalmemory_free_ring();

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. The must be released with the appropriate icalmemory_free_buffer() method.

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

Usage

// create buffer
char *buffer = icalmemory_new_buffer(50);

// fill buffer
strcpy(buffer, "some data");

// release buffer
icalmemory_free_buffer(buffer);

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() 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.

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);

icalmemory_strdup()

char* icalmemory_strdup

(

const char *

s

)

Create 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 appropriate free() method.

A wrapper around strdup(). Partly to trap calls to strdup(), partly because 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);
free(dup);

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

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);