Libical API Documentation 3.0

Functions
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. More...
void | icalmemory_append_char (char **buf, char **pos, size_t *buf_size, char ch)
| Appends a character to a buffer. More...
void | icalmemory_append_string (char **buf, char **pos, size_t *buf_size, const char *string)
| Appends a string to a buffer. More...
void | icalmemory_free_buffer (void *buf)
| Releases a buffer. More...
void | icalmemory_free_ring (void)
| Frees 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)
| Creates 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...

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

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

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_add_tmp_buffer
void icalmemory_add_tmp_buffer(void *buf)
Adds an externally allocated buffer to the ring.
Definition: icalmemory.c:182

## ◆ 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 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_free_buffer
void icalmemory_free_buffer(void *buf)
Releases a buffer.
Definition: icalmemory.c:287
icalmemory_new_buffer
void * icalmemory_new_buffer(size_t size)
Creates new buffer with the specified size.
Definition: icalmemory.c:261
icalmemory_append_char
void icalmemory_append_char(char **buf, char **pos, size_t *buf_size, char ch)
Appends a character to a buffer.
Definition: icalmemory.c:330

## ◆ 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);
icalmemory_append_string
void icalmemory_append_string(char **buf, char **pos, size_t *buf_size, const char *string)
Appends a string to a buffer.
Definition: icalmemory.c:292

## ◆ 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 |  | ) |

Frees 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_free_ring
void icalmemory_free_ring(void)
Frees all memory used in the ring.
Definition: icalmemory.c:227
icalmemory_tmp_buffer
void * icalmemory_tmp_buffer(size_t size)
Creates a new temporary buffer on the ring and returns it.
Definition: icalmemory.c:205

## ◆ 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()

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.

### 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_resize_buffer
void * icalmemory_resize_buffer(void *buf, size_t size)
Resizes a buffer created with icalmemory_new_buffer().
Definition: icalmemory.c:275

## ◆ 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 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_strdup
char * icalmemory_strdup(const char *s)
Creates a duplicate of a string.
Definition: icalmemory.c:251

## ◆ 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);
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.
Definition: icalmemory.c:242