Core repository-independent functions

Core repository-independent functions — Create, validate, and convert core data types

Functions

#define OSTREE_MAX_METADATA_SIZE
#define OSTREE_MAX_METADATA_WARN_SIZE
#define OSTREE_MAX_RECURSION
#define OSTREE_OBJECT_TYPE_IS_META()
const GVariantType * ostree_metadata_variant_type ()
gboolean ostree_validate_checksum_string ()
guchar * ostree_checksum_to_bytes ()
GVariant * ostree_checksum_to_bytes_v ()
char * ostree_checksum_from_bytes ()
char * ostree_checksum_from_bytes_v ()
void ostree_checksum_inplace_from_bytes ()
void ostree_checksum_inplace_to_bytes ()
const guchar * ostree_checksum_bytes_peek ()
const guchar * ostree_checksum_bytes_peek_validate ()
int ostree_cmp_checksum_bytes ()
gboolean ostree_validate_rev ()
gboolean ostree_parse_refspec ()
void ostree_checksum_update_meta ()
const char * ostree_object_type_to_string ()
OstreeObjectType ostree_object_type_from_string ()
guint ostree_hash_object_name ()
GVariant * ostree_object_name_serialize ()
void ostree_object_name_deserialize ()
char * ostree_object_to_string ()
void ostree_object_from_string ()
gboolean ostree_content_stream_parse ()
gboolean ostree_content_file_parse ()
gboolean ostree_raw_file_to_content_stream ()
gboolean ostree_checksum_file_from_input ()
gboolean ostree_checksum_file ()
void ostree_checksum_file_async ()
gboolean ostree_checksum_file_async_finish ()
GVariant * ostree_create_directory_metadata ()
gboolean ostree_validate_structureof_objtype ()
gboolean ostree_validate_structureof_csum_v ()
gboolean ostree_validate_structureof_checksum_string ()
gboolean ostree_validate_structureof_file_mode ()
gboolean ostree_validate_structureof_commit ()
gboolean ostree_validate_structureof_dirtree ()
gboolean ostree_validate_structureof_dirmeta ()
gchar * ostree_commit_get_parent ()
guint64 ostree_commit_get_timestamp ()

Types and Values

Description

These functions implement repository-independent algorithms for operating on the core OSTree data formats, such as converting GFileInfo into a GVariant.

There are 4 types of objects; file, dirmeta, tree, and commit. The last 3 are metadata, and the file object is the only content object type.

All metadata objects are stored as GVariant (big endian). The rationale for this is the same as that of the ext{2,3,4} family of filesystems; most developers will be using LE, and so it's better to continually test the BE->LE swap.

The file object is a custom format in order to support streaming.

Functions

OSTREE_MAX_METADATA_SIZE

#define OSTREE_MAX_METADATA_SIZE (10 * 1024 * 1024)

Maximum permitted size in bytes of metadata objects. This is an arbitrary number, but really, no one should be putting humongous data in metadata.


OSTREE_MAX_METADATA_WARN_SIZE

#define OSTREE_MAX_METADATA_WARN_SIZE (7 * 1024 * 1024)

Objects committed above this size will be allowed, but a warning will be emitted.


OSTREE_MAX_RECURSION

#define OSTREE_MAX_RECURSION (256)

Maximum depth of metadata.


OSTREE_OBJECT_TYPE_IS_META()

#define OSTREE_OBJECT_TYPE_IS_META(t) (t >= 2 && t <= 4)

Parameters

Returns

TRUE if object type is metadata


ostree_metadata_variant_type ()

const GVariantType *
ostree_metadata_variant_type (OstreeObjectType objtype);

ostree_validate_checksum_string ()

gboolean
ostree_validate_checksum_string (const char *sha256,
                                 GError **error);

Use this function to see if input strings are checksums.

Parameters

sha256

SHA256 hex string

 

error

Error

 

Returns

TRUE if sha256 is a valid checksum string, FALSE otherwise


ostree_checksum_to_bytes ()

guchar *
ostree_checksum_to_bytes (const char *checksum);

Parameters

checksum

An ASCII checksum

 

Returns

Binary checksum from checksum of length 32; free with g_free().

[transfer full][array fixed-size=32]


ostree_checksum_to_bytes_v ()

GVariant *
ostree_checksum_to_bytes_v (const char *checksum);

Parameters

checksum

An ASCII checksum

 

Returns

New GVariant of type ay with length 32.

[transfer full]


ostree_checksum_from_bytes ()

char *
ostree_checksum_from_bytes (const guchar *csum);

Parameters

csum

An binary checksum of length 32.

[array fixed-size=32]

Returns

String form of csum .

[transfer full]


ostree_checksum_from_bytes_v ()

char *
ostree_checksum_from_bytes_v (GVariant *csum_v);

Parameters

csum_v

GVariant of type ay

 

Returns

String form of csum_bytes .

[transfer full]


ostree_checksum_inplace_from_bytes ()

void
ostree_checksum_inplace_from_bytes (const guchar *csum,
                                    char *buf);

Overwrite the contents of buf with stringified version of csum .

[skip]

Parameters

csum

An binary checksum of length 32.

[array fixed-size=32]

buf

Output location, must be at least 65 bytes in length

 

ostree_checksum_inplace_to_bytes ()

void
ostree_checksum_inplace_to_bytes (const char *checksum,
                                  guchar *buf);

Convert checksum from a string to binary in-place, without allocating memory. Use this function in hot code paths.

Parameters

checksum

a SHA256 string

 

buf

Output buffer with at least 32 bytes of space

 

ostree_checksum_bytes_peek ()

const guchar *
ostree_checksum_bytes_peek (GVariant *bytes);

Parameters

bytes

GVariant of type ay

 

Returns

Binary checksum data in bytes ; do not free. If bytes does not have the correct length, return NULL.

[transfer none][array fixed-size=32][element-type guint8]


ostree_checksum_bytes_peek_validate ()

const guchar *
ostree_checksum_bytes_peek_validate (GVariant *bytes,
                                     GError **error);

Like ostree_checksum_bytes_peek(), but also throws error .

Parameters

bytes

GVariant of type ay

 

error

Errror

 

Returns

Binary checksum data.

[transfer none][array fixed-size=32][element-type guint8]


ostree_cmp_checksum_bytes ()

int
ostree_cmp_checksum_bytes (const guchar *a,
                           const guchar *b);

Compare two binary checksums, using memcmp().

Parameters

a

A binary checksum

 

b

A binary checksum

 

ostree_validate_rev ()

gboolean
ostree_validate_rev (const char *rev,
                     GError **error);

Parameters

rev

A revision string

 

error

Error

 

Returns

TRUE if rev is a valid ref string


ostree_parse_refspec ()

gboolean
ostree_parse_refspec (const char *refspec,
                      char **out_remote,
                      char **out_ref,
                      GError **error);

Split a refspec like "gnome-ostree:gnome-ostree/buildmaster" into two parts; out_remote will be set to "gnome-ostree", and out_ref will be "gnome-ostree/buildmaster".

If refspec refers to a local ref, out_remote will be NULL.

Parameters

refspec

A "refspec" string

 

out_remote

The remote name, or NULL if the refspec refs to a local ref.

[out][allow-none]

out_ref

Name of ref.

[out][allow-none]

error

Error

 

ostree_checksum_update_meta ()

void
ostree_checksum_update_meta (GChecksum *checksum,
                             GFileInfo *file_info,
                             GVariant *xattrs);

ostree_object_type_to_string ()

const char *
ostree_object_type_to_string (OstreeObjectType objtype);

Serialize objtype to a string; this is used for file extensions.

Parameters

objtype

an OstreeObjectType

 

ostree_object_type_from_string ()

OstreeObjectType
ostree_object_type_from_string (const char *str);

The reverse of ostree_object_type_to_string().

Parameters

str

A stringified version of OstreeObjectType

 

ostree_hash_object_name ()

guint
ostree_hash_object_name (gconstpointer a);

Use this function with GHashTable and ostree_object_name_serialize().

Parameters

a

A GVariant containing a serialized object

 

ostree_object_name_serialize ()

GVariant *
ostree_object_name_serialize (const char *checksum,
                              OstreeObjectType objtype);

Parameters

checksum

An ASCII checksum

 

objtype

An object type

 

Returns

A new floating GVariant containing checksum string and objtype.

[transfer floating]


ostree_object_name_deserialize ()

void
ostree_object_name_deserialize (GVariant *variant,
                                const char **out_checksum,
                                OstreeObjectType *out_objtype);

Reverse ostree_object_name_serialize(). Note that out_checksum is only valid for the lifetime of variant , and must not be freed.

Parameters

variant

A GVariant of type (su)

 

out_checksum

Pointer into string memory of variant with checksum.

[out][transfer none]

out_objtype

Return object type.

[out]

ostree_object_to_string ()

char *
ostree_object_to_string (const char *checksum,
                         OstreeObjectType objtype);

Parameters

checksum

An ASCII checksum

 

objtype

Object type

 

Returns

A string containing both checksum and a stringifed version of objtype


ostree_object_from_string ()

void
ostree_object_from_string (const char *str,
                           gchar **out_checksum,
                           OstreeObjectType *out_objtype);

Reverse ostree_object_to_string().

Parameters

str

An ASCII checksum

 

out_checksum

Parsed checksum.

[out][transfer full]

out_objtype

Parsed object type.

[out]

ostree_content_stream_parse ()

gboolean
ostree_content_stream_parse (gboolean compressed,
                             GInputStream *input,
                             guint64 input_length,
                             gboolean trusted,
                             GInputStream **out_input,
                             GFileInfo **out_file_info,
                             GVariant **out_xattrs,
                             GCancellable *cancellable,
                             GError **error);

The reverse of ostree_raw_file_to_content_stream(); this function converts an object content stream back into components.

Parameters

compressed

Whether or not the stream is zlib-compressed

 

input

Object content stream

 

input_length

Length of stream

 

trusted

If TRUE, assume the content has been validated

 

out_input

The raw file content stream.

[out]

out_file_info

Normal metadata.

[out]

out_xattrs

Extended attributes.

[out]

cancellable

Cancellable

 

error

Error

 

ostree_content_file_parse ()

gboolean
ostree_content_file_parse (gboolean compressed,
                           GFile *content_path,
                           gboolean trusted,
                           GInputStream **out_input,
                           GFileInfo **out_file_info,
                           GVariant **out_xattrs,
                           GCancellable *cancellable,
                           GError **error);

A thin wrapper for ostree_content_stream_parse(); this function converts an object content stream back into components.

Parameters

compressed

Whether or not the stream is zlib-compressed

 

content_path

Path to file containing content

 

trusted

If TRUE, assume the content has been validated

 

out_input

The raw file content stream.

[out]

out_file_info

Normal metadata.

[out]

out_xattrs

Extended attributes.

[out]

cancellable

Cancellable

 

error

Error

 

ostree_raw_file_to_content_stream ()

gboolean
ostree_raw_file_to_content_stream (GInputStream *input,
                                   GFileInfo *file_info,
                                   GVariant *xattrs,
                                   GInputStream **out_input,
                                   guint64 *out_length,
                                   GCancellable *cancellable,
                                   GError **error);

Convert from a "bare" file representation into an OSTREE_OBJECT_TYPE_FILE stream. This is a fundamental operation for writing data to an OstreeRepo.

Parameters

input

File raw content stream

 

file_info

A file info

 

xattrs

Optional extended attributes.

[allow-none]

out_input

Serialized object stream.

[out]

out_length

Length of stream.

[out]

cancellable

Cancellable

 

error

Error

 

ostree_checksum_file_from_input ()

gboolean
ostree_checksum_file_from_input (GFileInfo *file_info,
                                 GVariant *xattrs,
                                 GInputStream *in,
                                 OstreeObjectType objtype,
                                 guchar **out_csum,
                                 GCancellable *cancellable,
                                 GError **error);

Compute the OSTree checksum for a given input.

Parameters

file_info

File information

 

xattrs

Optional extended attributes.

[allow-none]

in

File content, should be NULL for symbolic links.

[allow-none]

objtype

Object type

 

out_csum

Return location for binary checksum.

[out][array fixed-size=32]

cancellable

Cancellable

 

error

Error

 

ostree_checksum_file ()

gboolean
ostree_checksum_file (GFile *f,
                      OstreeObjectType objtype,
                      guchar **out_csum,
                      GCancellable *cancellable,
                      GError **error);

Compute the OSTree checksum for a given file.

Parameters

f

File path

 

objtype

Object type

 

out_csum

Return location for binary checksum.

[out][array fixed-size=32]

cancellable

Cancellable

 

error

Error

 

ostree_checksum_file_async ()

void
ostree_checksum_file_async (GFile *f,
                            OstreeObjectType objtype,
                            int io_priority,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Asynchronously compute the OSTree checksum for a given file; complete with ostree_checksum_file_async_finish().

Parameters

f

File path

 

objtype

Object type

 

io_priority

Priority for operation, see G_IO_PRIORITY_DEFAULT

 

cancellable

Cancellable

 

callback

Invoked when operation is complete

 

user_data

Data for callback

 

ostree_checksum_file_async_finish ()

gboolean
ostree_checksum_file_async_finish (GFile *f,
                                   GAsyncResult *result,
                                   guchar **out_csum,
                                   GError **error);

Finish computing the OSTree checksum for a given file; see ostree_checksum_file_async().

Parameters

f

File path

 

result

Async result

 

out_csum

Return location for binary checksum.

[out][array fixed-size=32]

error

Error

 

ostree_create_directory_metadata ()

GVariant *
ostree_create_directory_metadata (GFileInfo *dir_info,
                                  GVariant *xattrs);

Parameters

dir_info

a GFileInfo containing directory information

 

xattrs

Optional extended attributes.

[allow-none]

Returns

A new GVariant containing OSTREE_OBJECT_TYPE_DIR_META.

[transfer full]


ostree_validate_structureof_objtype ()

gboolean
ostree_validate_structureof_objtype (guchar objtype,
                                     GError **error);

Parameters

error

Error

 

Returns

TRUE if objtype represents a valid object type


ostree_validate_structureof_csum_v ()

gboolean
ostree_validate_structureof_csum_v (GVariant *checksum,
                                    GError **error);

Parameters

checksum

a GVariant of type "ay"

 

error

Error

 

Returns

TRUE if checksum is a valid binary SHA256 checksum


ostree_validate_structureof_checksum_string ()

gboolean
ostree_validate_structureof_checksum_string
                               (const char *checksum,
                                GError **error);

Parameters

checksum

an ASCII string

 

error

Error

 

Returns

TRUE if checksum is a valid ASCII SHA256 checksum


ostree_validate_structureof_file_mode ()

gboolean
ostree_validate_structureof_file_mode (guint32 mode,
                                       GError **error);

Parameters

mode

A Unix filesystem mode

 

error

Error

 

Returns

TRUE if mode represents a valid file type and permissions


ostree_validate_structureof_commit ()

gboolean
ostree_validate_structureof_commit (GVariant *commit,
                                    GError **error);

Use this to validate the basic structure of commit , independent of any other objects it references.

Parameters

commit

A commit object, OSTREE_OBJECT_TYPE_COMMIT

 

error

Error

 

Returns

TRUE if commit is structurally valid


ostree_validate_structureof_dirtree ()

gboolean
ostree_validate_structureof_dirtree (GVariant *dirtree,
                                     GError **error);

Use this to validate the basic structure of dirtree , independent of any other objects it references.

Parameters

dirtree

A dirtree object, OSTREE_OBJECT_TYPE_DIR_TREE

 

error

Error

 

Returns

TRUE if dirtree is structurally valid


ostree_validate_structureof_dirmeta ()

gboolean
ostree_validate_structureof_dirmeta (GVariant *dirmeta,
                                     GError **error);

Use this to validate the basic structure of dirmeta .

Parameters

dirmeta

A dirmeta object, OSTREE_OBJECT_TYPE_DIR_META

 

error

Error

 

Returns

TRUE if dirmeta is structurally valid


ostree_commit_get_parent ()

gchar *
ostree_commit_get_parent (GVariant *commit_variant);

Parameters

commit_variant

Variant of type OSTREE_OBJECT_TYPE_COMMIT

 

Returns

Binary checksum with parent of commit_variant , or NULL if none


ostree_commit_get_timestamp ()

guint64
ostree_commit_get_timestamp (GVariant *commit_variant);

Types and Values

enum OstreeObjectType

Enumeration for core object types; OSTREE_OBJECT_TYPE_FILE is for content, the other types are metadata.

Members

OSTREE_OBJECT_TYPE_FILE

Content; regular file, symbolic link

 

OSTREE_OBJECT_TYPE_DIR_TREE

List of children (trees or files), and metadata

 

OSTREE_OBJECT_TYPE_DIR_META

Directory metadata

 

OSTREE_OBJECT_TYPE_COMMIT

Toplevel object, refers to tree and dirmeta for root

 

OSTREE_OBJECT_TYPE_LAST

#define OSTREE_OBJECT_TYPE_LAST OSTREE_OBJECT_TYPE_COMMIT

Last valid object type; use this to validate ranges.


OSTREE_DIRMETA_GVARIANT_STRING

#define OSTREE_DIRMETA_GVARIANT_STRING "(uuua(ayay))"

OSTREE_DIRMETA_GVARIANT_FORMAT

#define OSTREE_DIRMETA_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_DIRMETA_GVARIANT_STRING)

u - uid u - gid u - mode a(ayay) - xattrs


OSTREE_FILEMETA_GVARIANT_STRING

#define OSTREE_FILEMETA_GVARIANT_STRING "(uuua(ayay))"

OSTREE_FILEMETA_GVARIANT_FORMAT

#define OSTREE_FILEMETA_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_FILEMETA_GVARIANT_STRING)

This is not a regular object type, but used as an xattr on a .file object in bare-user repositories. This allows us to store metadata information that we can't store in the real filesystem but we can still use a regular .file object that we can hardlink to in the case of a user-mode checkout.

u - uid u - gid u - mode a(ayay) - xattrs


OSTREE_TREE_GVARIANT_STRING

#define OSTREE_TREE_GVARIANT_STRING "(a(say)a(sayay))"

OSTREE_TREE_GVARIANT_FORMAT

#define OSTREE_TREE_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_TREE_GVARIANT_STRING)

a(say) - array of (filename, checksum) for files a(sayay) - array of (dirname, tree_checksum, meta_checksum) for directories


OSTREE_COMMIT_GVARIANT_STRING

#define OSTREE_COMMIT_GVARIANT_STRING "(a{sv}aya(say)sstayay)"

OSTREE_COMMIT_GVARIANT_FORMAT

#define OSTREE_COMMIT_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_COMMIT_GVARIANT_STRING)

a{sv} - Metadata ay - parent checksum (empty string for initial) a(say) - Related objects s - subject s - body t - Timestamp in seconds since the epoch (UTC) ay - Root tree contents ay - Root tree metadata


OSTREE_SUMMARY_GVARIANT_STRING

#define OSTREE_SUMMARY_GVARIANT_STRING "(a(s(taya{sv}))a{sv})"

OSTREE_SUMMARY_GVARIANT_FORMAT

#define OSTREE_SUMMARY_GVARIANT_FORMAT G_VARIANT_TYPE (OSTREE_SUMMARY_GVARIANT_STRING)

refs: a(s(taya{sv})) - Map of ref name -> (latest commit size, latest commit checksum, additional metadata), sorted by ref name extensions: a{sv} - Additional metadata, none defined at the current time