GNOME.org

Core repository-independent functions

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

Synopsis

#define             OSTREE_MAX_METADATA_SIZE
#define             OSTREE_MAX_RECURSION
enum                OstreeObjectType;
#define             OSTREE_OBJECT_TYPE_IS_META          (t)
#define             OSTREE_OBJECT_TYPE_LAST
#define             OSTREE_DIRMETA_GVARIANT_FORMAT
#define             OSTREE_TREE_GVARIANT_FORMAT
#define             OSTREE_COMMIT_GVARIANT_FORMAT
const GVariantType * ostree_metadata_variant_type       (OstreeObjectType objtype);
gboolean            ostree_validate_checksum_string     (const char *sha256,
                                                         GError **error);
guchar *            ostree_checksum_to_bytes            (const char *checksum);
GVariant *          ostree_checksum_to_bytes_v          (const char *checksum);
char *              ostree_checksum_from_bytes          (const guchar *csum);
char *              ostree_checksum_from_bytes_v        (GVariant *csum_v);
void                ostree_checksum_inplace_from_bytes  (const guchar *csum,
                                                         char *buf);
void                ostree_checksum_inplace_to_bytes    (const char *checksum,
                                                         guchar *buf);
const guchar *      ostree_checksum_bytes_peek          (GVariant *bytes);
int                 ostree_cmp_checksum_bytes           (const guchar *a,
                                                         const guchar *b);
gboolean            ostree_validate_rev                 (const char *rev,
                                                         GError **error);
gboolean            ostree_parse_refspec                (const char *refspec,
                                                         char **out_remote,
                                                         char **out_ref,
                                                         GError **error);
void                ostree_checksum_update_meta         (GChecksum *checksum,
                                                         GFileInfo *file_info,
                                                         GVariant *xattrs);
const char *        ostree_object_type_to_string        (OstreeObjectType objtype);
OstreeObjectType    ostree_object_type_from_string      (const char *str);
guint               ostree_hash_object_name             (gconstpointer a);
GVariant *          ostree_object_name_serialize        (const char *checksum,
                                                         OstreeObjectType objtype);
void                ostree_object_name_deserialize      (GVariant *variant,
                                                         const char **out_checksum,
                                                         OstreeObjectType *out_objtype);
char *              ostree_object_to_string             (const char *checksum,
                                                         OstreeObjectType objtype);
void                ostree_object_from_string           (const char *str,
                                                         gchar **out_checksum,
                                                         OstreeObjectType *out_objtype);
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);
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);
gboolean            ostree_raw_file_to_content_stream   (GInputStream *input,
                                                         GFileInfo *file_info,
                                                         GVariant *xattrs,
                                                         GInputStream **out_input,
                                                         guint64 *out_length,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_checksum_file_from_input     (GFileInfo *file_info,
                                                         GVariant *xattrs,
                                                         GInputStream *in,
                                                         OstreeObjectType objtype,
                                                         guchar **out_csum,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            ostree_checksum_file                (GFile *f,
                                                         OstreeObjectType objtype,
                                                         guchar **out_csum,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                ostree_checksum_file_async          (GFile *f,
                                                         OstreeObjectType objtype,
                                                         int io_priority,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            ostree_checksum_file_async_finish   (GFile *f,
                                                         GAsyncResult *result,
                                                         guchar **out_csum,
                                                         GError **error);
GVariant *          ostree_create_directory_metadata    (GFileInfo *dir_info,
                                                         GVariant *xattrs);
gboolean            ostree_validate_structureof_objtype (guchar objtype,
                                                         GError **error);
gboolean            ostree_validate_structureof_csum_v  (GVariant *checksum,
                                                         GError **error);
gboolean            ostree_validate_structureof_checksum_string
                                                        (const char *checksum,
                                                         GError **error);
gboolean            ostree_validate_structureof_file_mode
                                                        (guint32 mode,
                                                         GError **error);
gboolean            ostree_validate_structureof_commit  (GVariant *commit,
                                                         GError **error);
gboolean            ostree_validate_structureof_dirtree (GVariant *dirtree,
                                                         GError **error);
gboolean            ostree_validate_structureof_dirmeta (GVariant *dirmeta,
                                                         GError **error);
gchar *             ostree_commit_get_parent            (GVariant *commit_variant);

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.

Details

OSTREE_MAX_METADATA_SIZE

#define OSTREE_MAX_METADATA_SIZE (1 << 26)

Maximum permitted size in bytes of metadata objects.

OSTREE_MAX_RECURSION

#define OSTREE_MAX_RECURSION (256)

Maximum depth of metadata.

enum OstreeObjectType

typedef enum {
  OSTREE_OBJECT_TYPE_FILE = 1,      /* .file */
  OSTREE_OBJECT_TYPE_DIR_TREE = 2,  /* .dirtree */
  OSTREE_OBJECT_TYPE_DIR_META = 3,  /* .dirmeta */
  OSTREE_OBJECT_TYPE_COMMIT = 4     /* .commit */
} OstreeObjectType;

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

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_IS_META()

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

t :

 An OstreeObjectType

Returns :

 TRUE if object type is metadata

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_FORMAT

#define OSTREE_DIRMETA_GVARIANT_FORMAT G_VARIANT_TYPE ("(uuua(ayay))")

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

OSTREE_TREE_GVARIANT_FORMAT

#define OSTREE_TREE_GVARIANT_FORMAT G_VARIANT_TYPE ("(a(say)a(sayay))")

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

OSTREE_COMMIT_GVARIANT_FORMAT

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

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

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

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

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

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

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.

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.

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

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_cmp_checksum_bytes ()

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

Compare two binary checksums, using memcmp().

a :

 A binary checksum

b :

 A binary checksum

ostree_validate_rev ()

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

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.

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.

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

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

a :

 A GVariant containing a serialized object

ostree_object_name_serialize ()

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

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.

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

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

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.

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.

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.

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.

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.

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

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

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

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

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

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

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

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.

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.

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.

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

commit_variant :

 Variant of type OSTREE_OBJECT_TYPE_COMMIT

Returns :

 Binary checksum with parent of commit_variant, or NULL if none
Generated by GTK-Doc V1.19