## Non-pageable Memory

Non-pageable Memory — Secure non-pageable memory

## Synopsis

    #define             gcr_secure_memory_new               (type,
                                                             n_objects)
    gpointer            gcr_secure_memory_alloc             (gsize size);
    gpointer            gcr_secure_memory_try_alloc         (gsize size);
    gpointer            gcr_secure_memory_realloc           (gpointer memory,
                                                             gsize size);
    gpointer            gcr_secure_memory_try_realloc       (gpointer memory,
                                                             gsize size);
    gchar *             gcr_secure_memory_strdup            (const gchar *string);
    void                gcr_secure_memory_strfree           (gchar *string);
    void                gcr_secure_memory_free              (gpointer memory);
    gboolean            gcr_secure_memory_is_secure         (gpointer memory);

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

## Details

### gcr_secure_memory_new()

    #define             gcr_secure_memory_new(type, n_objects)

Allocate objects in non-pageable memory.

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

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

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

`memory` : | pointer to reallocate or `NULL` to allocate a new block. [allow-none]
`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.

`memory` : | pointer to reallocate or `NULL` to allocate a new block. [allow-none]
`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.

`string` : | null terminated string to copy. [allow-none]
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.

`string` : | null terminated string to fere. [allow-none]

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

`memory` : | pointer to the beginning of the block of memory to free. [allow-none]

### gcr_secure_memory_is_secure ()

    gboolean            gcr_secure_memory_is_secure         (gpointer memory);

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

`memory` : | pointer to check
Returns : | whether the memory is secure non-pageable memory allocated by the Gcr library or not