Data Checksums: GLib Reference Manual

## Data Checksums Data Checksums — computes the checksum for data |

## Functions

gssize | g_checksum_type_get_length ()
GChecksum * | g_checksum_new ()
GChecksum * | g_checksum_copy ()
void | g_checksum_free ()
void | g_checksum_reset ()
void | g_checksum_update ()
const gchar * | g_checksum_get_string ()
void | g_checksum_get_digest ()
gchar * | g_compute_checksum_for_data ()
gchar * | g_compute_checksum_for_string ()
gchar * | g_compute_checksum_for_bytes ()

## Types and Values

enum | GChecksumType
| GChecksum

## Includes

    #include <glib.h>
    #include <glib/gi18n.h>

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

## Functions

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

#### Parameters

checksum_type | a GChecksumType |

#### Returns

the checksum length, or -1 if `checksum_type` is not supported.

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.

#### Parameters

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.

[transfer full]

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

checksum | a GChecksum |
data | buffer used to compute the checksum. | [array length=length][element-type guint8]
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.

#### Parameters

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

[skip]

#### Parameters

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

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.

#### Parameters

checksum_type | a GChecksumType |
data | binary blob to compute the digest of. | [array length=length][element-type guint8]
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.

#### Parameters

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.

#### Parameters

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

## Types and Values

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

#### Members

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 |
G_CHECKSUM_SHA512 | Use the SHA-512 hashing algorithm (Since: 2.36) |
G_CHECKSUM_SHA384 | Use the SHA-384 hashing algorithm (Since: 2.51) |

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