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);

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

Generated by GTK-Doc V1.14