Root partition mount point: OSTree API references

## Root partition mount point Root partition mount point — Manage physical root filesystem |

## Functions

OstreeSysroot * | ostree_sysroot_new ()
OstreeSysroot * | ostree_sysroot_new_default ()
GFile * | ostree_sysroot_get_path ()
gboolean | ostree_sysroot_load ()
gboolean | ostree_sysroot_load_if_changed ()
gboolean | ostree_sysroot_lock ()
gboolean | ostree_sysroot_try_lock ()
void | ostree_sysroot_lock_async ()
gboolean | ostree_sysroot_lock_finish ()
void | ostree_sysroot_unlock ()
void | ostree_sysroot_unload ()
int | ostree_sysroot_get_fd ()
gboolean | ostree_sysroot_ensure_initialized ()
int | ostree_sysroot_get_bootversion ()
int | ostree_sysroot_get_subbootversion ()
GPtrArray * | ostree_sysroot_get_deployments ()
OstreeDeployment * | ostree_sysroot_get_booted_deployment ()
GFile * | ostree_sysroot_get_deployment_directory ()
char * | ostree_sysroot_get_deployment_dirpath ()
GFile * | ostree_sysroot_get_deployment_origin_path ()
gboolean | ostree_sysroot_cleanup ()
gboolean | ostree_sysroot_prepare_cleanup ()
gboolean | ostree_sysroot_get_repo ()
gboolean | ostree_sysroot_init_osname ()
gboolean | ostree_sysroot_deployment_set_kargs ()
gboolean | ostree_sysroot_deployment_set_mutable ()
gboolean | ostree_sysroot_deployment_unlock ()
gboolean | ostree_sysroot_write_deployments ()
gboolean | ostree_sysroot_write_origin_file ()
gboolean | ostree_sysroot_deploy_tree ()
OstreeDeployment * | ostree_sysroot_get_merge_deployment ()
GKeyFile * | ostree_sysroot_origin_new_from_refspec ()
gboolean | ostree_sysroot_simple_write_deployment ()

## Types and Values

typedef | OstreeSysroot
enum | OstreeSysrootSimpleWriteDeploymentFlags

## Description

A OstreeSysroot object represents a physical root filesystem, which in particular should contain a toplevel /ostree directory. Inside this directory is an OstreeRepo in /ostree/repo, plus a set of deployments in /ostree/deploy.

This class is not by default safe against concurrent use by threads or external processes. You can use `ostree_sysroot_lock()` to perform locking externally.

## Functions

### ostree_sysroot_new ()

    OstreeSysroot *
    ostree_sysroot_new (GFile *path);

#### Parameters

path | Path to a system root directory, or `NULL`. | [allow-none]

#### Returns

An accessor object for an system root located at `path` .

[transfer full]

### ostree_sysroot_new_default ()

    OstreeSysroot *
    ostree_sysroot_new_default (void);

#### Returns

An accessor for the current visible root / filesystem.

[transfer full]

### ostree_sysroot_get_path ()

    GFile *
    ostree_sysroot_get_path (OstreeSysroot *self);

#### Returns

Path to rootfs.

[transfer none]

### ostree_sysroot_load ()

    gboolean
    ostree_sysroot_load (OstreeSysroot *self,
                         GCancellable *cancellable,
                         GError **error);

Load deployment list, bootversion, and subbootversion from the rootfs `self` .

#### Parameters

self | Sysroot |
cancellable | Cancellable |
error | Error |

### ostree_sysroot_load_if_changed ()

    gboolean
    ostree_sysroot_load_if_changed (OstreeSysroot *self,
                                    gboolean *out_changed,
                                    GCancellable *cancellable,
                                    GError **error);

### ostree_sysroot_lock ()

    gboolean
    ostree_sysroot_lock (OstreeSysroot *self,
                         GError **error);

Acquire an exclusive multi-process write lock for `self` . This call blocks until the lock has been acquired. The lock is not reentrant.

Release the lock with `ostree_sysroot_unlock()`. The lock will also be released if `self` is deallocated.

#### Parameters

self | Self |
error | Error |

### ostree_sysroot_try_lock ()

    gboolean
    ostree_sysroot_try_lock (OstreeSysroot *self,
                             gboolean *out_acquired,
                             GError **error);

Try to acquire an exclusive multi-process write lock for `self` . If another process holds the lock, this function will return immediately, setting `out_acquired` to `FALSE`, and returning `TRUE` (and no error).

Release the lock with `ostree_sysroot_unlock()`. The lock will also be released if `self` is deallocated.

#### Parameters

self | Self |
out_acquired | Whether or not the lock has been acquired. | [out]
error | Error |

### ostree_sysroot_lock_async ()

    void
    ostree_sysroot_lock_async (OstreeSysroot *self,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

An asynchronous version of `ostree_sysroot_lock()`.

#### Parameters

self | Self |
cancellable | Cancellable |
callback | Callback |
user_data | User data |

### ostree_sysroot_lock_finish ()

    gboolean
    ostree_sysroot_lock_finish (OstreeSysroot *self,
                                GAsyncResult *result,
                                GError **error);

Call when `ostree_sysroot_lock_async()` is ready.

#### Parameters

self | Self |
result | Result |
error | Error |

### ostree_sysroot_unlock ()

    void
    ostree_sysroot_unlock (OstreeSysroot *self);

Clear the lock previously acquired with `ostree_sysroot_lock()`. It is safe to call this function if the lock has not been previously acquired.

#### Parameters

self | Self |

### ostree_sysroot_unload ()

    void
    ostree_sysroot_unload (OstreeSysroot *self);

Release any resources such as file descriptors referring to the root directory of this sysroot. Normally, those resources are cleared by finalization, but in garbage collected languages that may not be predictable.

This undoes the effect of ``ostree_sysroot_load()``.

#### Parameters

self | Sysroot |

### ostree_sysroot_get_fd ()

    int
    ostree_sysroot_get_fd (OstreeSysroot *self);

Access a file descriptor that refers to the root directory of this sysroot. `ostree_sysroot_load()` must have been invoked prior to calling this function.

#### Parameters

self | Sysroot |

#### Returns

A file descriptor valid for the lifetime of `self`

### ostree_sysroot_ensure_initialized ()

    gboolean
    ostree_sysroot_ensure_initialized (OstreeSysroot *self,
                                       GCancellable *cancellable,
                                       GError **error);

Ensure that `self` is set up as a valid rootfs, by creating /ostree/repo, among other things.

#### Parameters

self | Sysroot |
cancellable | Cancellable |
error | Error |

### ostree_sysroot_get_bootversion ()

    int
    ostree_sysroot_get_bootversion (OstreeSysroot *self);

### ostree_sysroot_get_subbootversion ()

    int
    ostree_sysroot_get_subbootversion (OstreeSysroot *self);

### ostree_sysroot_get_deployments ()

    GPtrArray *
    ostree_sysroot_get_deployments (OstreeSysroot *self);

#### Parameters

self | Sysroot |

#### Returns

Ordered list of deployments.

[element-type OstreeDeployment][transfer container]

### ostree_sysroot_get_booted_deployment ()

    OstreeDeployment *
    ostree_sysroot_get_booted_deployment (OstreeSysroot *self);

#### Parameters

self | Sysroot |

#### Returns

The currently booted deployment, or `NULL` if none.

[transfer none]

### ostree_sysroot_get_deployment_directory ()

    GFile *
    ostree_sysroot_get_deployment_directory
                                   (OstreeSysroot *self,
                                    OstreeDeployment *deployment);

#### Parameters

self | Sysroot |
deployment | A deployment |

#### Returns

Path to deployment root directory.

[transfer full]

### ostree_sysroot_get_deployment_dirpath ()

    char *
    ostree_sysroot_get_deployment_dirpath (OstreeSysroot *self,
                                           OstreeDeployment *deployment);

Note this function only returns a *relative* path - if you want to access, it, you must either use fd-relative api such as `openat()`, or concatenate it with the full `ostree_sysroot_get_path()`.

#### Parameters

self | Repo |
deployment | A deployment |

#### Returns

Path to deployment root directory, relative to sysroot.

[transfer full]

### ostree_sysroot_get_deployment_origin_path ()

    GFile *
    ostree_sysroot_get_deployment_origin_path
                                   (GFile *deployment_path);

#### Parameters

deployment_path | A deployment path |

#### Returns

Path to deployment origin file.

[transfer full]

### ostree_sysroot_cleanup ()

    gboolean
    ostree_sysroot_cleanup (OstreeSysroot *self,
                            GCancellable *cancellable,
                            GError **error);

Delete any state that resulted from a partially completed transaction, such as incomplete deployments.

#### Parameters

self | Sysroot |
cancellable | Cancellable |
error | Error |

### ostree_sysroot_prepare_cleanup ()

    gboolean
    ostree_sysroot_prepare_cleanup (OstreeSysroot *self,
                                    GCancellable *cancellable,
                                    GError **error);

Like `ostree_sysroot_cleanup()` in that it cleans up incomplete deployments and old boot versions, but does NOT prune the repository.

#### Parameters

self | Sysroot |
cancellable | Cancellable |
error | Error |

### ostree_sysroot_get_repo ()

    gboolean
    ostree_sysroot_get_repo (OstreeSysroot *self,
                             OstreeRepo **out_repo,
                             GCancellable *cancellable,
                             GError **error);

Retrieve the OSTree repository in sysroot `self` .

#### Parameters

self | Sysroot |
out_repo | Repository in sysroot `self` . | [out]
cancellable | Cancellable |
error | Error |

### ostree_sysroot_init_osname ()

    gboolean
    ostree_sysroot_init_osname (OstreeSysroot *self,
                                const char *osname,
                                GCancellable *cancellable,
                                GError **error);

Initialize the directory structure for an "osname", which is a group of operating system deployments, with a shared `/var`. One is required for generating a deployment.

#### Parameters

self | Sysroot |
osname | Name group of operating system checkouts |
cancellable | Cancellable |
error | Error |

### ostree_sysroot_deployment_set_kargs ()

    gboolean
    ostree_sysroot_deployment_set_kargs (OstreeSysroot *self,
                                         OstreeDeployment *deployment,
                                         char **new_kargs,
                                         GCancellable *cancellable,
                                         GError **error);

Entirely replace the kernel arguments of `deployment` with the values in `new_kargs` .

#### Parameters

self | Sysroot |
deployment | A deployment |
new_kargs | Replace deployment's kernel arguments. | [array zero-terminated=1][element-type utf8]
cancellable | Cancellable |
error | Error |

### ostree_sysroot_deployment_set_mutable ()

    gboolean
    ostree_sysroot_deployment_set_mutable (OstreeSysroot *self,
                                           OstreeDeployment *deployment,
                                           gboolean is_mutable,
                                           GCancellable *cancellable,
                                           GError **error);

By default, deployment directories are not mutable. This function will allow making them temporarily mutable, for example to allow layering additional non-OSTree content.

#### Parameters

self | Sysroot |
deployment | A deployment |
is_mutable | Whether or not deployment's files can be changed |
error | Error |

### ostree_sysroot_deployment_unlock ()

    gboolean
    ostree_sysroot_deployment_unlock (OstreeSysroot *self,
                                      OstreeDeployment *deployment,
                                      OstreeDeploymentUnlockedState unlocked_state,
                                      GCancellable *cancellable,
                                      GError **error);

Configure the target deployment `deployment` such that it is writable. There are multiple modes, essentially differing in whether or not any changes persist across reboot.

The `OSTREE_DEPLOYMENT_UNLOCKED_HOTFIX` state is persistent across reboots.

#### Parameters

self | Sysroot |
deployment | Deployment |
unlocked_state | Transition to this unlocked state |
cancellable | Cancellable |
error | Error |

### ostree_sysroot_write_deployments ()

    gboolean
    ostree_sysroot_write_deployments (OstreeSysroot *self,
                                      GPtrArray *new_deployments,
                                      GCancellable *cancellable,
                                      GError **error);

Assuming `new_deployments` have already been deployed in place on disk, atomically update bootloader configuration.

#### Parameters

self | Sysroot |
new_deployments | List of new deployments. | [element-type OstreeDeployment]
cancellable | Cancellable |
error | Error |

### ostree_sysroot_write_origin_file ()

    gboolean
    ostree_sysroot_write_origin_file (OstreeSysroot *sysroot,
                                      OstreeDeployment *deployment,
                                      GKeyFile *new_origin,
                                      GCancellable *cancellable,
                                      GError **error);

Immediately replace the origin file of the referenced `deployment` with the contents of `new_origin` . If `new_origin` is `NULL`, this function will write the current origin of `deployment` .

#### Parameters

sysroot | System root |
deployment | Deployment |
new_origin | Origin content. | [allow-none]
cancellable | Cancellable |
error | Error |

### ostree_sysroot_deploy_tree ()

    gboolean
    ostree_sysroot_deploy_tree (OstreeSysroot *self,
                                const char *osname,
                                const char *revision,
                                GKeyFile *origin,
                                OstreeDeployment *provided_merge_deployment,
                                char **override_kernel_argv,
                                OstreeDeployment **out_new_deployment,
                                GCancellable *cancellable,
                                GError **error);

Check out deployment tree with revision `revision` , performing a 3 way merge with `provided_merge_deployment` for configuration.

#### Parameters

self | Sysroot |
osname | osname to use for merge deployment. | [allow-none]
revision | Checksum to add |
origin | Origin to use for upgrades. | [allow-none]
provided_merge_deployment | Use this deployment for merge path. | [allow-none]
override_kernel_argv | Use these as kernel arguments; if `NULL`, inherit options from provided_merge_deployment. | [allow-none][array zero-terminated=1][element-type utf8]
out_new_deployment | The new deployment path. | [out]
cancellable | Cancellable |
error | Error |

### ostree_sysroot_get_merge_deployment ()

    OstreeDeployment *
    ostree_sysroot_get_merge_deployment (OstreeSysroot *self,
                                         const char *osname);

Find the deployment to use as a configuration merge source; this is the first one in the current deployment list which matches osname.

#### Parameters

self | Sysroot |
osname | Operating system group. | [allow-none]

#### Returns

Configuration merge deployment.

[transfer full]

### ostree_sysroot_origin_new_from_refspec ()

    GKeyFile *
    ostree_sysroot_origin_new_from_refspec
                                   (OstreeSysroot *self,
                                    const char *refspec);

#### Parameters

refspec | A refspec |

#### Returns

A new config file which sets `refspec` as an origin.

[transfer full]

### ostree_sysroot_simple_write_deployment ()

    gboolean
    ostree_sysroot_simple_write_deployment
                                   (OstreeSysroot *sysroot,
                                    const char *osname,
                                    OstreeDeployment *new_deployment,
                                    OstreeDeployment *merge_deployment,
                                    OstreeSysrootSimpleWriteDeploymentFlags flags,
                                    GCancellable *cancellable,
                                    GError **error);

Prepend `new_deployment` to the list of deployments, commit, and cleanup. By default, all other deployments for the given `osname` except the merge deployment and the booted deployment will be garbage collected.

If `OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN` is specified, then all current deployments will be kept.

If `OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NOT_DEFAULT` is specified, then instead of prepending, the new deployment will be added right after the booted or merge deployment, instead of first.

#### Parameters

sysroot | Sysroot |
osname | OS name. | [allow-none]
new_deployment | Prepend this deployment to the list |
merge_deployment | Use this deployment for configuration merge. | [allow-none]
flags | Flags controlling behavior |
cancellable | Cancellable |
error | Error |

## Types and Values

### OstreeSysroot

    typedef struct OstreeSysroot OstreeSysroot;

### enum OstreeSysrootSimpleWriteDeploymentFlags

#### Members

OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NONE |  |
OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_RETAIN |  |
OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NOT_DEFAULT |  |
OSTREE_SYSROOT_SIMPLE_WRITE_DEPLOYMENT_FLAGS_NO_CLEAN |  |