GI.OSTree.Objects.Sysroot

No description available in the introspection data.

Exported types

newtype Sysroot

Memory-managed wrapper type.

Constructors

Sysroot (ManagedPtr Sysroot)

Instances

Eq Sysroot

Defined in GI.OSTree.Objects.Sysroot

Methods

(==) :: Sysroot -> Sysroot -> Bool

(/=) :: Sysroot -> Sysroot -> Bool

GObject Sysroot

Defined in GI.OSTree.Objects.Sysroot

ManagedPtrNewtype Sysroot

Defined in GI.OSTree.Objects.Sysroot

Methods

toManagedPtr :: Sysroot -> ManagedPtr Sysroot

TypedObject Sysroot

Defined in GI.OSTree.Objects.Sysroot

Methods

glibType :: IO GType

HasParentTypes Sysroot

Defined in GI.OSTree.Objects.Sysroot

IsGValue (Maybe Sysroot)

Convert Sysroot to and from GValue. See toGValue and fromGValue.

Defined in GI.OSTree.Objects.Sysroot

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Sysroot -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Sysroot)

type ParentTypes Sysroot

Defined in GI.OSTree.Objects.Sysroot

type ParentTypes Sysroot = '[Object]

class (GObject o, IsDescendantOf Sysroot o) => IsSysroot o

Type class for types which can be safely cast to Sysroot, for instance with toSysroot.

Instances

(GObject o, IsDescendantOf Sysroot o) => IsSysroot o

Defined in GI.OSTree.Objects.Sysroot

toSysroot :: (MonadIO m, IsSysroot o) => o -> m Sysroot

Cast to Sysroot, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

bindProperty, bindPropertyFull, cleanup, cleanupPruneRepo, deployTree, deployTreeWithOptions, deploymentSetKargs, deploymentSetMutable, deploymentSetPinned, deploymentUnlock, ensureInitialized, forceFloating, freezeNotify, getv, initOsname, initialize, isBooted, isFloating, load, loadIfChanged, lock, lockAsync, lockFinish, notify, notifyByPspec, originNewFromRefspec, prepareCleanup, queryDeploymentsFor, ref, refSink, repo, requireBootedDeployment, runDispose, simpleWriteDeployment, stageOverlayInitrd, stageTree, stageTreeWithOptions, stealData, stealQdata, thawNotify, tryLock, unload, unlock, unref, watchClosure, writeDeployments, writeDeploymentsWithOptions, writeOriginFile.

Getters

getBootedDeployment, getBootversion, getData, getDeploymentDirectory, getDeploymentDirpath, getDeployments, getFd, getMergeDeployment, getPath, getProperty, getQdata, getRepo, getStagedDeployment, getSubbootversion.

Setters

setData, setDataFull, setMountNamespaceInUse, setProperty.

cleanup

sysrootCleanup

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

self: Sysroot

-> Maybe b

cancellable: Cancellable

-> m ()

(Can throw GError)

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

cleanupPruneRepo

sysrootCleanupPruneRepo

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

sysroot: Sysroot

-> RepoPruneOptions

options: Flags controlling pruning

-> Maybe b

cancellable: Cancellable

-> m (Int32, Int32, Word64)

(Can throw GError)

Prune the system repository. This is a thin wrapper around repoPruneFromReachable; the primary addition is that this function automatically gathers all deployed commits into the reachable set.

You generally want to at least set the OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY flag in options. A commit traversal depth of 0 is assumed.

Locking: exclusive

Since: 2018.6

deployTree

sysrootDeployTree

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b, IsCancellable c)

=> a

self: Sysroot

-> Maybe Text

osname: osname to use for merge deployment

-> Text

revision: Checksum to add

-> Maybe KeyFile

origin: Origin to use for upgrades

-> Maybe b

providedMergeDeployment: Use this deployment for merge path

-> Maybe [Text]

overrideKernelArgv: Use these as kernel arguments; if Nothing, inherit options from provided_merge_deployment

-> Maybe c

cancellable: Cancellable

-> m Deployment

(Can throw GError)

Older version of sysrootStageTreeWithOptions.

Since: 2018.5

deployTreeWithOptions

sysrootDeployTreeWithOptions

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b, IsCancellable c)

=> a

self: Sysroot

-> Maybe Text

osname: osname to use for merge deployment

-> Text

revision: Checksum to add

-> Maybe KeyFile

origin: Origin to use for upgrades

-> Maybe b

providedMergeDeployment: Use this deployment for merge path

-> Maybe SysrootDeployTreeOpts

opts: Options

-> Maybe c

cancellable: Cancellable

-> m Deployment

(Can throw GError)

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

When booted into the sysroot, you should use the sysrootStageTree API instead.

Since: 2020.7

deploymentSetKargs

sysrootDeploymentSetKargs

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b, IsCancellable c)

=> a

self: Sysroot

-> b

deployment: A deployment

-> [Text]

newKargs: Replace deployment's kernel arguments

-> Maybe c

cancellable: Cancellable

-> m ()

(Can throw GError)

Entirely replace the kernel arguments of deployment with the values in newKargs.

deploymentSetMutable

sysrootDeploymentSetMutable

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b, IsCancellable c)

=> a

self: Sysroot

-> b

deployment: A deployment

-> Bool

isMutable: Whether or not deployment's files can be changed

-> Maybe c

cancellable: Cancellable

-> m ()

(Can throw GError)

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

deploymentSetPinned

sysrootDeploymentSetPinned

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b)

=> a

self: Sysroot

-> b

deployment: A deployment

-> Bool

isPinned: Whether or not deployment will be automatically GC'd

-> m ()

(Can throw GError)

By default, deployments may be subject to garbage collection. Typical uses of libostree only retain at most 2 deployments. If isPinned is TRUE, a metadata bit will be set causing libostree to avoid automatic GC of the deployment. However, this is really an "advisory" note; it's still possible for e.g. older versions of libostree unaware of pinning to GC the deployment.

This function does nothing and returns successfully if the deployment is already in the desired pinning state. It is an error to try to pin the staged deployment (as it's not in the bootloader entries).

Since: 2018.3

deploymentUnlock

sysrootDeploymentUnlock

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b, IsCancellable c)

=> a

self: Sysroot

-> b

deployment: Deployment

-> DeploymentUnlockedState

unlockedState: Transition to this unlocked state

-> Maybe c

cancellable: Cancellable

-> m ()

(Can throw GError)

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.

Since: 2016.4

ensureInitialized

sysrootEnsureInitialized

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

self: Sysroot

-> Maybe b

cancellable: Cancellable

-> m ()

(Can throw GError)

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

getBootedDeployment

sysrootGetBootedDeployment

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> m (Maybe Deployment)

Returns: The currently booted deployment, or Nothing if none

No description available in the introspection data.

getBootversion

sysrootGetBootversion :: (HasCallStack, MonadIO m, IsSysroot a) => a -> m Int32

No description available in the introspection data.

getDeploymentDirectory

sysrootGetDeploymentDirectory

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b)

=> a

self: Sysroot

-> b

deployment: A deployment

-> m File

Returns: Path to deployment root directory

No description available in the introspection data.

getDeploymentDirpath

sysrootGetDeploymentDirpath

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b)

=> a

self: Repo

-> b

deployment: A deployment

-> m Text

Returns: Path to deployment root directory, relative to sysroot

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

getDeploymentOriginPath

sysrootGetDeploymentOriginPath

Arguments

:: (HasCallStack, MonadIO m, IsFile a)

=> a

deploymentPath: A deployment path

-> m File

Returns: Path to deployment origin file

No description available in the introspection data.

getDeployments

sysrootGetDeployments

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> m [Deployment]

Returns: Ordered list of deployments

No description available in the introspection data.

getFd

sysrootGetFd

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> m Int32

Returns: A file descriptor valid for the lifetime of self

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

getMergeDeployment

sysrootGetMergeDeployment

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> Maybe Text

osname: Operating system group

-> m (Maybe Deployment)

Returns: Configuration merge deployment

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

getPath

sysrootGetPath

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> m File

Returns: Path to rootfs

No description available in the introspection data.

getRepo

sysrootGetRepo

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

self: Sysroot

-> Maybe b

cancellable: Cancellable

-> m Repo

(Can throw GError)

Retrieve the OSTree repository in sysroot self. The repo is guaranteed to be open (see repoOpen).

getStagedDeployment

sysrootGetStagedDeployment

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> m (Maybe Deployment)

Returns: The currently staged deployment, or Nothing if none

No description available in the introspection data.

Since: 2018.5

getSubbootversion

sysrootGetSubbootversion :: (HasCallStack, MonadIO m, IsSysroot a) => a -> m Int32

No description available in the introspection data.

initOsname

sysrootInitOsname

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

self: Sysroot

-> Text

osname: Name group of operating system checkouts

-> Maybe b

cancellable: Cancellable

-> m ()

(Can throw GError)

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.

Since: 2016.4

initialize

sysrootInitialize

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: sysroot

-> m ()

(Can throw GError)

Subset of sysrootLoad; performs basic initialization. Notably, one can invoke ostree_sysroot_get_fd() after calling this function.

It is not necessary to call this function if sysrootLoad is invoked.

Since: 2020.1

isBooted

sysrootIsBooted

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> m Bool

Returns: True iff the sysroot points to a booted deployment

Can only be invoked after ostree_sysroot_initialize().

Since: 2020.1

load

sysrootLoad

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

self: Sysroot

-> Maybe b

cancellable: Cancellable

-> m ()

(Can throw GError)

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

lock

sysrootLock

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Self

-> m ()

(Can throw GError)

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 sysrootUnlock. The lock will also be released if self is deallocated.

lockAsync

sysrootLockAsync

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

self: Self

-> Maybe b

cancellable: Cancellable

-> Maybe AsyncReadyCallback

callback: Callback

-> m ()

An asynchronous version of sysrootLock.

lockFinish

sysrootLockFinish

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsAsyncResult b)

=> a

self: Self

-> b

result: Result

-> m ()

(Can throw GError)

Call when sysrootLockAsync is ready.

new

sysrootNew

Arguments

:: (HasCallStack, MonadIO m, IsFile a)

=> Maybe a

path: Path to a system root directory, or Nothing to use the current visible root file system

-> m Sysroot

Returns: An accessor object for an system root located at path

Create a new Sysroot object for the sysroot at path. If path is Nothing, the current visible root file system is used, equivalent to sysrootNewDefault.

newDefault

sysrootNewDefault

Arguments

:: (HasCallStack, MonadIO m)

=> m Sysroot

Returns: An accessor for the current visible root / filesystem

No description available in the introspection data.

originNewFromRefspec

sysrootOriginNewFromRefspec

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> Text

refspec: A refspec

-> m KeyFile

Returns: A new config file which sets refspec as an origin

No description available in the introspection data.

prepareCleanup

sysrootPrepareCleanup

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

self: Sysroot

-> Maybe b

cancellable: Cancellable

-> m ()

(Can throw GError)

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

queryDeploymentsFor

sysrootQueryDeploymentsFor

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> Maybe Text

osname: "stateroot" name

-> m (Maybe Deployment, Maybe Deployment)

Find the pending and rollback deployments for osname. Pass Nothing for osname to use the booted deployment's osname. By default, pending deployment is the first deployment in the order that matches osname, and rollback will be the next one after the booted deployment, or the deployment after the pending if we're not looking at the booted deployment.

Since: 2017.7

repo

sysrootRepo

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> m Repo

Returns: The OSTree repository in sysroot self.

This function is a variant of sysrootGetRepo that cannot fail, and returns a cached repository. Can only be called after sysrootInitialize or sysrootLoad has been invoked successfully.

Since: 2017.7

requireBootedDeployment

sysrootRequireBootedDeployment

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> m Deployment

Returns: The currently booted deployment, or an error (Can throw GError)

Find the booted deployment, or return an error if not booted via OSTree.

Since: 2021.1

setMountNamespaceInUse

sysrootSetMountNamespaceInUse :: (HasCallStack, MonadIO m, IsSysroot a) => a -> m ()

If this function is invoked, then libostree will assume that a private Linux mount namespace has been created by the process. The primary use case for this is to have e.g. /sysroot mounted read-only by default.

If this function has been called, then when a function which requires writable access is invoked, libostree will automatically remount as writable any mount points on which it operates. This currently is just /sysroot and /boot.

If you invoke this function, it must be before sysrootLoad; it may be invoked before or after sysrootInitialize.

Since: 2020.1

simpleWriteDeployment

sysrootSimpleWriteDeployment

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b, IsDeployment c, IsCancellable d)

=> a

sysroot: Sysroot

-> Maybe Text

osname: OS name

-> b

newDeployment: Prepend this deployment to the list

-> Maybe c

mergeDeployment: Use this deployment for configuration merge

-> [SysrootSimpleWriteDeploymentFlags]

flags: Flags controlling behavior

-> Maybe d

cancellable: Cancellable

-> m ()

(Can throw GError)

Prepend newDeployment 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 SysrootSimpleWriteDeploymentFlagsRetain is specified, then all current deployments will be kept.

If SysrootSimpleWriteDeploymentFlagsRetainPending is specified, then pending deployments will be kept.

If SysrootSimpleWriteDeploymentFlagsRetainRollback is specified, then rollback deployments will be kept.

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

If SysrootSimpleWriteDeploymentFlagsNoClean is specified, then no cleanup will be performed after adding the deployment. Make sure to call sysrootCleanup sometime later, instead.

stageOverlayInitrd

sysrootStageOverlayInitrd

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

self: Sysroot

-> Int32

fd: File descriptor to overlay initrd

-> Maybe b

cancellable: Cancellable

-> m Text

(Can throw GError)

Stage an overlay initrd to be used in an upcoming deployment. Returns a checksum which can be passed to sysrootDeployTreeWithOptions or sysrootStageTreeWithOptions via the overlay_initrds array option.

Since: 2020.7

stageTree

sysrootStageTree

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b, IsCancellable c)

=> a

self: Sysroot

-> Maybe Text

osname: osname to use for merge deployment

-> Text

revision: Checksum to add

-> Maybe KeyFile

origin: Origin to use for upgrades

-> Maybe b

mergeDeployment: Use this deployment for merge path

-> Maybe [Text]

overrideKernelArgv: Use these as kernel arguments; if Nothing, inherit options from provided_merge_deployment

-> Maybe c

cancellable: Cancellable

-> m Deployment

(Can throw GError)

Older version of sysrootStageTreeWithOptions.

Since: 2018.5

stageTreeWithOptions

sysrootStageTreeWithOptions

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b, IsCancellable c)

=> a

self: Sysroot

-> Maybe Text

osname: osname to use for merge deployment

-> Text

revision: Checksum to add

-> Maybe KeyFile

origin: Origin to use for upgrades

-> Maybe b

mergeDeployment: Use this deployment for merge path

-> SysrootDeployTreeOpts

opts: Options

-> Maybe c

cancellable: Cancellable

-> m Deployment

(Can throw GError)

Like sysrootDeployTree, but "finalization" only occurs at OS shutdown time.

Since: 2020.7

tryLock

sysrootTryLock

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Self

-> m Bool

(Can throw GError)

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

Release the lock with sysrootUnlock. The lock will also be released if self is deallocated.

unload

sysrootUnload

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Sysroot

-> m ()

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

unlock

sysrootUnlock

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a)

=> a

self: Self

-> m ()

Clear the lock previously acquired with sysrootLock. It is safe to call this function if the lock has not been previously acquired.

writeDeployments

sysrootWriteDeployments

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

self: Sysroot

-> [Deployment]

newDeployments: List of new deployments

-> Maybe b

cancellable: Cancellable

-> m ()

(Can throw GError)

Older version of sysrootWriteDeploymentsWithOptions. This version will perform post-deployment cleanup by default.

writeDeploymentsWithOptions

sysrootWriteDeploymentsWithOptions

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsCancellable b)

=> a

self: Sysroot

-> [Deployment]

newDeployments: List of new deployments

-> SysrootWriteDeploymentsOpts

opts: Options

-> Maybe b

cancellable: Cancellable

-> m ()

(Can throw GError)

Assuming newDeployments have already been deployed in place on disk via sysrootDeployTree, atomically update bootloader configuration. By default, no post-transaction cleanup will be performed. You should invoke sysrootCleanup at some point after the transaction, or specify do_postclean in opts. Skipping the post-transaction cleanup is useful if for example you want to control pruning of the repository.

Since: 2017.4

writeOriginFile

sysrootWriteOriginFile

Arguments

:: (HasCallStack, MonadIO m, IsSysroot a, IsDeployment b, IsCancellable c)

=> a

sysroot: System root

-> b

deployment: Deployment

-> Maybe KeyFile

newOrigin: Origin content

-> Maybe c

cancellable: Cancellable

-> m ()

(Can throw GError)

Immediately replace the origin file of the referenced deployment with the contents of newOrigin. If newOrigin is Nothing, this function will write the current origin of deployment.

Properties

path

No description available in the introspection data.

constructSysrootPath :: (IsSysroot o, MonadIO m, IsFile a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “path” property. This is rarely needed directly, but it is used by new.

getSysrootPath :: (MonadIO m, IsSysroot o) => o -> m File

Get the value of the “path” property. When overloading is enabled, this is equivalent to

get sysroot #path

Signals

journalMsg

type SysrootJournalMsgCallback

Arguments

 = Text

msg: Human-readable string (should not contain newlines)

-> IO ()

libostree will log to the journal various events, such as the /etc merge status, and transaction completion. Connect to this signal to also synchronously receive the text for those messages. This is intended to be used by command line tools which link to libostree as a library.

Currently, the structured data is only available via the systemd journal.

Since: 2017.10

afterSysrootJournalMsg :: (IsSysroot a, MonadIO m) => a -> ((?self :: a) => SysrootJournalMsgCallback) -> m SignalHandlerId

Connect a signal handler for the journalMsg signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after sysroot #journalMsg callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onSysrootJournalMsg :: (IsSysroot a, MonadIO m) => a -> ((?self :: a) => SysrootJournalMsgCallback) -> m SignalHandlerId

Connect a signal handler for the journalMsg signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on sysroot #journalMsg callback