Data Checksums

Data Checksums — computes the checksum for data

Functions

Types and Values

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][nullable]

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.

[transfer full]

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 a 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, or NULL if g_checksum_new() fails for checksum_type . The returned string should be freed with g_free() when done using it.

[transfer full][nullable]

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, or NULL if g_checksum_new() fails for checksum_type . The returned string should be freed with g_free() when done using it.

[transfer full][nullable]

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, or NULL if g_checksum_new() fails for checksum_type . The returned string should be freed with g_free() when done using it.

[transfer full][nullable]

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