## Data Checksums

Data Checksums — computes the checksum for data

## Synopsis

    #include <glib.h>

    enum                GChecksumType;
    gssize              g_checksum_type_get_length          (GChecksumType checksum_type);
                        GChecksum;
    GChecksum *         g_checksum_new                      (GChecksumType checksum_type);
    GChecksum *         g_checksum_copy                     (const GChecksum *checksum);
    void                g_checksum_free                     (GChecksum *checksum);
    void                g_checksum_reset                    (GChecksum *checksum);
    void                g_checksum_update                   (GChecksum *checksum,
                                                             const guchar *data,
                                                             gssize length);
    const gchar *       g_checksum_get_string               (GChecksum *checksum);
    void                g_checksum_get_digest               (GChecksum *checksum,
                                                             guint8 *buffer,
                                                             gsize *digest_len);

    gchar *             g_compute_checksum_for_data         (GChecksumType checksum_type,
                                                             const guchar *data,
                                                             gsize length);
    gchar *             g_compute_checksum_for_string       (GChecksumType checksum_type,
                                                             const gchar *str,
                                                             gssize length);
    gchar *             g_compute_checksum_for_bytes        (GChecksumType checksum_type,
                                                             GBytes *data);

## Description

GLib provides a generic API for computing checksums (or "digests") for a sequence of arbitrary bytes, using various hashing algorithms like MD5, SHA-1 and SHA-256. Checksums are commonly used in various environments and specifications.

GLib supports incremental checksums using the GChecksum data structure, by calling `g_checksum_update()` as long as there's data available and then using `g_checksum_get_string()` or `g_checksum_get_digest()` to compute the checksum and return it either as a string in hexadecimal form, or as a raw sequence of bytes. To compute the checksum for binary blobs and NUL-terminated strings in one go, use the convenience functions `g_compute_checksum_for_data()` and `g_compute_checksum_for_string()`, respectively.

Support for checksums has been added in GLib 2.16

## Details

### enum GChecksumType

    typedef enum {
      G_CHECKSUM_MD5,
      G_CHECKSUM_SHA1,
      G_CHECKSUM_SHA256
    } GChecksumType;

The hashing algorithm to be used by GChecksum when performing the digest of some data.

Note that the GChecksumType enumeration may be extended at a later date to include new hashing algorithm types.

`G_CHECKSUM_MD5` | Use the MD5 hashing algorithm
`G_CHECKSUM_SHA1` | Use the SHA-1 hashing algorithm
`G_CHECKSUM_SHA256` | Use the SHA-256 hashing algorithm

Since 2.16

### g_checksum_type_get_length ()

    gssize              g_checksum_type_get_length          (GChecksumType checksum_type);

Gets the length in bytes of digests of type `checksum_type`

`checksum_type` : | a GChecksumType
Returns : | the checksum length, or -1 if `checksum_type` is not supported.

Since 2.16

### GChecksum

    typedef struct _GChecksum GChecksum;

An opaque structure representing a checksumming operation. To create a new GChecksum, use `g_checksum_new()`. To free a GChecksum, use `g_checksum_free()`.

Since 2.16

### g_checksum_new ()

    GChecksum *         g_checksum_new                      (GChecksumType checksum_type);

Creates a new GChecksum, using the checksum algorithm `checksum_type`. If the `checksum_type` is not known, `NULL` is returned. A GChecksum can be used to compute the checksum, or digest, of an arbitrary binary blob, using different hashing algorithms.

A GChecksum works by feeding a binary blob through `g_checksum_update()` until there is data to be checked; the digest can then be extracted using `g_checksum_get_string()`, which will return the checksum as a hexadecimal string; or `g_checksum_get_digest()`, which will return a vector of raw bytes. Once either `g_checksum_get_string()` or `g_checksum_get_digest()` have been called on a GChecksum, the checksum will be closed and it won't be possible to call `g_checksum_update()` on it anymore.

`checksum_type` : | the desired type of checksum
Returns : | the newly created GChecksum, or `NULL`. Use `g_checksum_free()` to free the memory allocated by it.

Since 2.16

### g_checksum_copy ()

    GChecksum *         g_checksum_copy                     (const GChecksum *checksum);

Copies a GChecksum. If `checksum` has been closed, by calling `g_checksum_get_string()` or `g_checksum_get_digest()`, the copied checksum will be closed as well.

`checksum` : | the GChecksum to copy
Returns : | the copy of the passed GChecksum. Use `g_checksum_free()` when finished using it.

Since 2.16

### g_checksum_free ()

    void                g_checksum_free                     (GChecksum *checksum);

Frees the memory allocated for `checksum`.

`checksum` : | a GChecksum

Since 2.16

### g_checksum_reset ()

    void                g_checksum_reset                    (GChecksum *checksum);

Resets the state of the `checksum` back to its initial state.

`checksum` : | the GChecksum to reset

Since 2.18

### g_checksum_update ()

    void                g_checksum_update                   (GChecksum *checksum,
                                                             const guchar *data,
                                                             gssize length);

Feeds `data` into an existing GChecksum. The checksum must still be open, that is `g_checksum_get_string()` or `g_checksum_get_digest()` must not have been called on `checksum`.

`checksum` : | a GChecksum
`data` : | buffer used to compute the checksum
`length` : | size of the buffer, or -1 if it is a null-terminated string.

Since 2.16

### g_checksum_get_string ()

    const gchar *       g_checksum_get_string               (GChecksum *checksum);

Gets the digest as an hexadecimal string.

Once this function has been called the GChecksum can no longer be updated with `g_checksum_update()`.

The hexadecimal characters will be lower case.

`checksum` : | a GChecksum
Returns : | the hexadecimal representation of the checksum. The returned string is owned by the checksum and should not be modified or freed.

Since 2.16

### g_checksum_get_digest ()

    void                g_checksum_get_digest               (GChecksum *checksum,
                                                             guint8 *buffer,
                                                             gsize *digest_len);

Gets the digest from `checksum` as a raw binary vector and places it into `buffer`. The size of the digest depends on the type of checksum.

Once this function has been called, the GChecksum is closed and can no longer be updated with `g_checksum_update()`.

`checksum` : | a GChecksum
`buffer` : | output buffer
`digest_len` : | an inout parameter. The caller initializes it to the size of `buffer`. After the call it contains the length of the digest.

Since 2.16

### g_compute_checksum_for_data ()

    gchar *             g_compute_checksum_for_data         (GChecksumType checksum_type,
                                                             const guchar *data,
                                                             gsize length);

Computes the checksum for a binary `data` of `length`. This is a convenience wrapper for `g_checksum_new()`, `g_checksum_get_string()` and `g_checksum_free()`.

The hexadecimal string returned will be in lower case.

`checksum_type` : | a GChecksumType
`data` : | binary blob to compute the digest of
`length` : | length of `data`
Returns : | the digest of the binary data as a string in hexadecimal. The returned string should be freed with `g_free()` when done using it.

Since 2.16

### g_compute_checksum_for_string ()

    gchar *             g_compute_checksum_for_string       (GChecksumType checksum_type,
                                                             const gchar *str,
                                                             gssize length);

Computes the checksum of a string.

The hexadecimal string returned will be in lower case.

`checksum_type` : | a GChecksumType
`str` : | the string to compute the checksum of
`length` : | the length of the string, or -1 if the string is null-terminated.
Returns : | the checksum as a hexadecimal string. The returned string should be freed with `g_free()` when done using it.

Since 2.16

### g_compute_checksum_for_bytes ()

    gchar *             g_compute_checksum_for_bytes        (GChecksumType checksum_type,
                                                             GBytes *data);

Computes the checksum for a binary `data`. This is a convenience wrapper for `g_checksum_new()`, `g_checksum_get_string()` and `g_checksum_free()`.

The hexadecimal string returned will be in lower case.

`checksum_type` : | a GChecksumType
`data` : | binary blob to compute the digest of
Returns : | the digest of the binary data as a string in hexadecimal. The returned string should be freed with `g_free()` when done using it.

Since 2.34