Non-pageable Memory: Gcr Library Reference Manual

## Non-pageable Memory Non-pageable Memory — Secure non-pageable memory |

## Functions

#define | gcr_secure_memory_new()
gpointer | gcr_secure_memory_alloc ()
gpointer | gcr_secure_memory_try_alloc ()
gpointer | gcr_secure_memory_realloc ()
gpointer | gcr_secure_memory_try_realloc ()
gchar * | gcr_secure_memory_strdup ()
void | gcr_secure_memory_strfree ()
void | gcr_secure_memory_free ()
gboolean | gcr_secure_memory_is_secure ()

## Description

Normal allocated memory can be paged to disk at the whim of the operating system. This can be a problem for sensitive information like passwords, keys and secrets.

The Gcr library holds passwords and keys in non-pageable, or locked memory. This is only possible if the OS contains support for it.

These functions allow applications to use secure memory to hold passwords and other sensitive information.

## Functions

### gcr_secure_memory_new()

    #define             gcr_secure_memory_new(type, n_objects)

Allocate objects in non-pageable memory.

#### Parameters

type | C type of the objects to allocate |
n_objects | number of objects to allocate |

#### Returns

the new block of memory.

[transfer full]

### gcr_secure_memory_alloc ()

    gpointer
    gcr_secure_memory_alloc (gsize size);

Allocate a block of non-pageable memory.

If non-pageable memory cannot be allocated then normal memory will be returned.

[skip]

#### Parameters

size | The new desired size of the memory block. |

#### Returns

new memory block which should be freed with `gcr_secure_memory_free()`.

[transfer full]

### gcr_secure_memory_try_alloc ()

    gpointer
    gcr_secure_memory_try_alloc (gsize size);

Allocate a block of non-pageable memory.

If non-pageable memory cannot be allocated, then `NULL` is returned.

[skip]

#### Parameters

size | new desired size of the memory block |

#### Returns

new block, or `NULL` if memory cannot be allocated; memory block should be freed with `gcr_secure_memory_free()`.

[transfer full]

### gcr_secure_memory_realloc ()

    gpointer
    gcr_secure_memory_realloc (gpointer memory,
                               gsize size);

Reallocate a block of non-pageable memory.

Glib memory is also reallocated correctly. If called with a null pointer, then a new block of memory is allocated. If called with a zero size, then the block of memory is freed.

If non-pageable memory cannot be allocated then normal memory will be returned.

[skip]

#### Parameters

memory | pointer to reallocate or `NULL` to allocate a new block. | [nullable]
size | new desired size of the memory block, or 0 to free the memory |

#### Returns

new block, or `NULL` if the block was freed; memory block should be freed with `gcr_secure_memory_free()`.

[transfer full]

### gcr_secure_memory_try_realloc ()

    gpointer
    gcr_secure_memory_try_realloc (gpointer memory,
                                   gsize size);

Reallocate a block of non-pageable memory.

Glib memory is also reallocated correctly when passed to this function. If called with a null pointer, then a new block of memory is allocated. If called with a zero size, then the block of memory is freed.

If memory cannot be allocated, `NULL` is returned and the original block of memory remains intact.

[skip]

#### Parameters

memory | pointer to reallocate or `NULL` to allocate a new block. | [nullable]
size | new desired size of the memory block |

#### Returns

the new block, or `NULL` if memory cannot be allocated; the memory block should be freed with `gcr_secure_memory_free()`.

[transfer full]

### gcr_secure_memory_strdup ()

    gchar *
    gcr_secure_memory_strdup (const gchar *string);

Copy a string into non-pageable memory. If the input string is `NULL`, then `NULL` will be returned.

[skip]

#### Parameters

string | null terminated string to copy. | [nullable]

#### Returns

copied string, should be freed with `gcr_secure_memory_free()`

### gcr_secure_memory_strfree ()

    void
    gcr_secure_memory_strfree (gchar *string);

Free a string, whether securely allocated using these functions or not. This will also clear out the contents of the string so they do not remain in memory.

[skip]

#### Parameters

string | null terminated string to fere. | [nullable]

### gcr_secure_memory_free ()

    void
    gcr_secure_memory_free (gpointer memory);

Free a block of non-pageable memory.

Glib memory is also freed correctly when passed to this function. If called with a `NULL` pointer then no action is taken.

[skip]

#### Parameters

memory | pointer to the beginning of the block of memory to free. | [nullable]

### gcr_secure_memory_is_secure ()

    gboolean
    gcr_secure_memory_is_secure (gpointer memory);

Check if a pointer is in non-pageable memory allocated by.

[skip]

#### Parameters

memory | pointer to check |

#### Returns

whether the memory is secure non-pageable memory allocated by the Gcr library or not