guestfs_add_cdrom

int guestfs_add_cdrom (guestfs_h *handle,
                const char *filename);

This function adds a virtual CD-ROM disk image to the guest.

This is equivalent to the qemu parameter -cdrom filename.

This function returns 0 on success or -1 on error.

guestfs_add_drive

int guestfs_add_drive (guestfs_h *handle,
                const char *filename);

This function adds a virtual machine disk image filename to the guest. The first time you call this function, the disk appears as IDE disk 0 (/dev/sda) in the guest, the second time as /dev/sdb, and so on.

You don't necessarily need to be root when using libguestfs. However you obviously do need sufficient permissions to access the filename for whatever operations you want to perform (ie. read access if you just want to read the image or write access if you want to modify the image).

This is equivalent to the qemu parameter -drive file=filename.

This function returns 0 on success or -1 on error.

guestfs_aug_close

int guestfs_aug_close (guestfs_h *handle);

Close the current Augeas handle and free up any resources used by it. After calling this, you have to call guestfs_aug_init again before you can use any other Augeas functions.

This function returns 0 on success or -1 on error.

guestfs_aug_defnode

struct guestfs_int_bool *guestfs_aug_defnode (guestfs_h *handle,
                const char *name,
                const char *expr,
                const char *val);

Defines a variable name whose value is the result of evaluating expr.

If expr evaluates to an empty nodeset, a node is created, equivalent to calling guestfs_aug_set expr, value. name will be the nodeset containing that single node.

On success this returns a pair containing the number of nodes in the nodeset, and a boolean flag if a node was created.

This function returns a struct guestfs_int_bool *, or NULL if there was an error. The caller must call guestfs_free_int_bool after use.

guestfs_aug_defvar

int guestfs_aug_defvar (guestfs_h *handle,
                const char *name,
                const char *expr);

Defines an Augeas variable name whose value is the result of evaluating expr. If expr is NULL, then name is undefined.

On success this returns the number of nodes in expr, or 0 if expr evaluates to something which is not a nodeset.

On error this function returns -1.

guestfs_aug_get

char *guestfs_aug_get (guestfs_h *handle,
                const char *path);

Look up the value associated with path. If path matches exactly one node, the value is returned.

This function returns a string, or NULL on error. The caller must free the returned string after use.

guestfs_aug_init

int guestfs_aug_init (guestfs_h *handle,
                const char *root,
                int flags);

Create a new Augeas handle for editing configuration files. If there was any previous Augeas handle associated with this guestfs session, then it is closed.

You must call this before using any other guestfs_aug_* commands.

root is the filesystem root. root must not be NULL, use / instead.

The flags are the same as the flags defined in <augeas.h>, the logical or of the following integers:

AUG_SAVE_BACKUP = 1: Keep the original file with a .augsave extension.
AUG_SAVE_NEWFILE = 2: Save changes into a file with extension .augnew, and do not overwrite original. Overrides AUG_SAVE_BACKUP.
AUG_TYPE_CHECK = 4: Typecheck lenses (can be expensive).
AUG_NO_STDINC = 8: Do not use standard load path for modules.
AUG_SAVE_NOOP = 16: Make save a no-op, just record what would have been changed.
AUG_NO_LOAD = 32: Do not load the tree in guestfs_aug_init.

To close the handle, you can call guestfs_aug_close.

To find out more about Augeas, see http://augeas.net/.

This function returns 0 on success or -1 on error.

guestfs_aug_insert

int guestfs_aug_insert (guestfs_h *handle,
                const char *path,
                const char *label,
                int before);

Create a new sibling label for path, inserting it into the tree before or after path (depending on the boolean flag before).

path must match exactly one existing node in the tree, and label must be a label, ie. not contain /, * or end with a bracketed index [N].

This function returns 0 on success or -1 on error.

guestfs_aug_load

int guestfs_aug_load (guestfs_h *handle);

Load files into the tree.

See aug_load in the Augeas documentation for the full gory details.

This function returns 0 on success or -1 on error.

guestfs_aug_ls

char **guestfs_aug_ls (guestfs_h *handle,
                const char *path);

This is just a shortcut for listing guestfs_aug_match path/* and sorting the resulting nodes into alphabetical order.

This function returns a NULL-terminated array of strings (like environ(3)), or NULL if there was an error. The caller must free the strings and the array after use.

guestfs_aug_match

char **guestfs_aug_match (guestfs_h *handle,
                const char *path);

Returns a list of paths which match the path expression path. The returned paths are sufficiently qualified so that they match exactly one node in the current tree.

This function returns a NULL-terminated array of strings (like environ(3)), or NULL if there was an error. The caller must free the strings and the array after use.

guestfs_aug_mv

int guestfs_aug_mv (guestfs_h *handle,
                const char *src,
                const char *dest);

Move the node src to dest. src must match exactly one node. dest is overwritten if it exists.

This function returns 0 on success or -1 on error.

guestfs_aug_rm

int guestfs_aug_rm (guestfs_h *handle,
                const char *path);

Remove path and all of its children.

On success this returns the number of entries which were removed.

On error this function returns -1.

guestfs_aug_save

int guestfs_aug_save (guestfs_h *handle);

This writes all pending changes to disk.

The flags which were passed to guestfs_aug_init affect exactly how files are saved.

This function returns 0 on success or -1 on error.

guestfs_aug_set

int guestfs_aug_set (guestfs_h *handle,
                const char *path,
                const char *val);

Set the value associated with path to value.

This function returns 0 on success or -1 on error.

guestfs_blockdev_flushbufs

int guestfs_blockdev_flushbufs (guestfs_h *handle,
                const char *device);

This tells the kernel to flush internal buffers associated with device.

This uses the blockdev(8) command.

This function returns 0 on success or -1 on error.

guestfs_blockdev_getbsz

int guestfs_blockdev_getbsz (guestfs_h *handle,
                const char *device);

This returns the block size of a device.

(Note this is different from both size in blocks and filesystem block size).

This uses the blockdev(8) command.

On error this function returns -1.

guestfs_blockdev_getro

int guestfs_blockdev_getro (guestfs_h *handle,
                const char *device);

Returns a boolean indicating if the block device is read-only (true if read-only, false if not).

This uses the blockdev(8) command.

This function returns a C truth value on success or -1 on error.

guestfs_blockdev_getsize64

int64_t guestfs_blockdev_getsize64 (guestfs_h *handle,
                const char *device);

This returns the size of the device in bytes.

guestfs_blockdev_getss

int guestfs_blockdev_getss (guestfs_h *handle,
                const char *device);

This returns the size of sectors on a block device. Usually 512, but can be larger for modern devices.

(Note, this is not the size in sectors, use guestfs_blockdev_getsz for that).

This uses the blockdev(8) command.

On error this function returns -1.

guestfs_blockdev_getsz

int64_t guestfs_blockdev_getsz (guestfs_h *handle,
                const char *device);

This returns the size of the device in units of 512-byte sectors (even if the sectorsize isn't 512 bytes ... weird).

See also guestfs_blockdev_getss for the real sector size of the device, and guestfs_blockdev_getsize64 for the more useful size in bytes.

This uses the blockdev(8) command.

On error this function returns -1.

guestfs_blockdev_rereadpt

int guestfs_blockdev_rereadpt (guestfs_h *handle,
                const char *device);

Reread the partition table on device.

This uses the blockdev(8) command.

This function returns 0 on success or -1 on error.

guestfs_blockdev_setbsz

int guestfs_blockdev_setbsz (guestfs_h *handle,
                const char *device,
                int blocksize);

This sets the block size of a device.

(Note this is different from both size in blocks and filesystem block size).

This uses the blockdev(8) command.

This function returns 0 on success or -1 on error.

guestfs_blockdev_setro

int guestfs_blockdev_setro (guestfs_h *handle,
                const char *device);

Sets the block device named device to read-only.

This uses the blockdev(8) command.

This function returns 0 on success or -1 on error.

guestfs_blockdev_setrw

int guestfs_blockdev_setrw (guestfs_h *handle,
                const char *device);

Sets the block device named device to read-write.

This uses the blockdev(8) command.

This function returns 0 on success or -1 on error.

guestfs_cat

char *guestfs_cat (guestfs_h *handle,
                const char *path);

Return the contents of the file named path.

Note that this function cannot correctly handle binary files (specifically, files containing \0 character which is treated as end of string). For those you need to use the guestfs_download function which has a more complex interface.

This function returns a string, or NULL on error. The caller must free the returned string after use.

Because of the message protocol, there is a transfer limit of somewhere between 2MB and 4MB. To transfer large files you should use FTP.

guestfs_checksum

char *guestfs_checksum (guestfs_h *handle,
                const char *csumtype,
                const char *path);

This call computes the MD5, SHAx or CRC checksum of the file named path.

The type of checksum to compute is given by the csumtype parameter which must have one of the following values:

crc: Compute the cyclic redundancy check (CRC) specified by POSIX for the cksum command.
md5: Compute the MD5 hash (using the md5sum program).
sha1: Compute the SHA1 hash (using the sha1sum program).
sha224: Compute the SHA224 hash (using the sha224sum program).
sha256: Compute the SHA256 hash (using the sha256sum program).
sha384: Compute the SHA384 hash (using the sha384sum program).
sha512: Compute the SHA512 hash (using the sha512sum program).

The checksum is returned as a printable string.

This function returns a string, or NULL on error. The caller must free the returned string after use.

guestfs_chmod

int guestfs_chmod (guestfs_h *handle,
                int mode,
                const char *path);

Change the mode (permissions) of path to mode. Only numeric modes are supported.

This function returns 0 on success or -1 on error.

guestfs_chown

int guestfs_chown (guestfs_h *handle,
                int owner,
                int group,
                const char *path);

Change the file owner to owner and group to group.

Only numeric uid and gid are supported. If you want to use names, you will need to locate and parse the password file yourself (Augeas support makes this relatively easy).

This function returns 0 on success or -1 on error.

guestfs_command

char *guestfs_command (guestfs_h *handle,
                char * const* const arguments);

This call runs a command from the guest filesystem. The filesystem must be mounted, and must contain a compatible operating system (ie. something Linux, with the same or compatible processor architecture).

The single parameter is an argv-style list of arguments. The first element is the name of the program to run. Subsequent elements are parameters. The list must be non-empty (ie. must contain a program name).

The $PATH environment variable will contain at least /usr/bin and /bin. If you require a program from another location, you should provide the full path in the first parameter.

Shared libraries and data files required by the program must be available on filesystems which are mounted in the correct places. It is the caller's responsibility to ensure all filesystems that are needed are mounted at the right locations.

This function returns a string, or NULL on error. The caller must free the returned string after use.

guestfs_command_lines

char **guestfs_command_lines (guestfs_h *handle,
                char * const* const arguments);

This is the same as guestfs_command, but splits the result into a list of lines.

This function returns a NULL-terminated array of strings (like environ(3)), or NULL if there was an error. The caller must free the strings and the array after use.

guestfs_config

int guestfs_config (guestfs_h *handle,
                const char *qemuparam,
                const char *qemuvalue);

This can be used to add arbitrary qemu command line parameters of the form -param value. Actually it's not quite arbitrary - we prevent you from setting some parameters which would interfere with parameters that we use.

The first character of param string must be a - (dash).

value can be NULL.

This function returns 0 on success or -1 on error.

guestfs_debug

char *guestfs_debug (guestfs_h *handle,
                const char *subcmd,
                char * const* const extraargs);

The guestfs_debug command exposes some internals of guestfsd (the guestfs daemon) that runs inside the qemu subprocess.

There is no comprehensive help for this command. You have to look at the file daemon/debug.c in the libguestfs source to find out what you can do.

This function returns a string, or NULL on error. The caller must free the returned string after use.

guestfs_download

int guestfs_download (guestfs_h *handle,
                const char *remotefilename,
                const char *filename);

Download file remotefilename and save it as filename on the local machine.

filename can also be a named pipe.

See also guestfs_upload, guestfs_cat.

This function returns 0 on success or -1 on error.

guestfs_exists

int guestfs_exists (guestfs_h *handle,
                const char *path);

This returns true if and only if there is a file, directory (or anything) with the given path name.

See also guestfs_is_file, guestfs_is_dir, guestfs_stat.

This function returns a C truth value on success or -1 on error.

guestfs_file

char *guestfs_file (guestfs_h *handle,
                const char *path);

This call uses the standard file(1) command to determine the type or contents of the file. This also works on devices, for example to find out whether a partition contains a filesystem.

The exact command which runs is file -bsL path. Note in particular that the filename is not prepended to the output (the -b option).

This function returns a string, or NULL on error. The caller must free the returned string after use.

guestfs_fsck

int guestfs_fsck (guestfs_h *handle,
                const char *fstype,
                const char *device);

This runs the filesystem checker (fsck) on device which should have filesystem type fstype.

The returned integer is the status. See fsck(8) for the list of status codes from fsck.

Notes:

Multiple status codes can be summed together.
A non-zero return code can mean "success", for example if errors have been corrected on the filesystem.
Checking or repairing NTFS volumes is not supported (by linux-ntfs).

This command is entirely equivalent to running fsck -a -t fstype device.

On error this function returns -1.

guestfs_get_autosync

int guestfs_get_autosync (guestfs_h *handle);

Get the autosync flag.

This function returns a C truth value on success or -1 on error.

guestfs_get_e2label

char *guestfs_get_e2label (guestfs_h *handle,
                const char *device);

This returns the ext2/3/4 filesystem label of the filesystem on device.

This function returns a string, or NULL on error. The caller must free the returned string after use.

guestfs_get_e2uuid

char *guestfs_get_e2uuid (guestfs_h *handle,
                const char *device);

This returns the ext2/3/4 filesystem UUID of the filesystem on device.

This function returns a string, or NULL on error. The caller must free the returned string after use.

guestfs_get_path

const char *guestfs_get_path (guestfs_h *handle);

Return the current search path.

This is always non-NULL. If it wasn't set already, then this will return the default path.

This function returns a string, or NULL on error. The string is owned by the guest handle and must not be freed.

guestfs_get_qemu

const char *guestfs_get_qemu (guestfs_h *handle);

Return the current qemu binary.

This is always non-NULL. If it wasn't set already, then this will return the default qemu binary name.

This function returns a string, or NULL on error. The string is owned by the guest handle and must not be freed.

guestfs_get_state

int guestfs_get_state (guestfs_h *handle);

This returns the current state as an opaque integer. This is only useful for printing debug and internal error messages.

For more information on states, see guestfs(3).

On error this function returns -1.

guestfs_get_verbose

int guestfs_get_verbose (guestfs_h *handle);

This returns the verbose messages flag.

This function returns a C truth value on success or -1 on error.

guestfs_is_busy

int guestfs_is_busy (guestfs_h *handle);

This returns true iff this handle is busy processing a command (in the BUSY state).

For more information on states, see guestfs(3).

This function returns a C truth value on success or -1 on error.

guestfs_is_config

int guestfs_is_config (guestfs_h *handle);

This returns true iff this handle is being configured (in the CONFIG state).

For more information on states, see guestfs(3).

This function returns a C truth value on success or -1 on error.

guestfs_is_dir

int guestfs_is_dir (guestfs_h *handle,
                const char *path);

This returns true if and only if there is a directory with the given path name. Note that it returns false for other objects like files.

guestfs_is_file

int guestfs_is_file (guestfs_h *handle,
                const char *path);

This returns true if and only if there is a file with the given path name. Note that it returns false for other objects like directories.

guestfs_is_launching

int guestfs_is_launching (guestfs_h *handle);

This returns true iff this handle is launching the subprocess (in the LAUNCHING state).

For more information on states, see guestfs(3).

This function returns a C truth value on success or -1 on error.

guestfs_is_ready

int guestfs_is_ready (guestfs_h *handle);

This returns true iff this handle is ready to accept commands (in the READY state).

For more information on states, see guestfs(3).

This function returns a C truth value on success or -1 on error.

guestfs_kill_subprocess

int guestfs_kill_subprocess (guestfs_h *handle);

This kills the qemu subprocess. You should never need to call this.

This function returns 0 on success or -1 on error.

guestfs_launch

int guestfs_launch (guestfs_h *handle);

Internally libguestfs is implemented by running a virtual machine using qemu(1).

You should call this after configuring the handle (eg. adding drives) but before performing any actions.

This function returns 0 on success or -1 on error.

guestfs_list_devices

char **guestfs_list_devices (guestfs_h *handle);

List all the block devices.

The full block device names are returned, eg. /dev/sda

This function returns a NULL-terminated array of strings (like environ(3)), or NULL if there was an error. The caller must free the strings and the array after use.

guestfs_list_partitions

char **guestfs_list_partitions (guestfs_h *handle);

List all the partitions detected on all block devices.

The full partition device names are returned, eg. /dev/sda1

This does not return logical volumes. For that you will need to call guestfs_lvs.

This function returns a NULL-terminated array of strings (like environ(3)), or NULL if there was an error. The caller must free the strings and the array after use.

guestfs_ll

char *guestfs_ll (guestfs_h *handle,
                const char *directory);

List the files in directory (relative to the root directory, there is no cwd) in the format of 'ls -la'.

This command is mostly useful for interactive sessions. It is not intended that you try to parse the output string.

This function returns a string, or NULL on error. The caller must free the returned string after use.

guestfs_ls

char **guestfs_ls (guestfs_h *handle,
                const char *directory);

List the files in directory (relative to the root directory, there is no cwd). The '.' and '..' entries are not returned, but hidden files are shown.

This command is mostly useful for interactive sessions. Programs should probably use guestfs_readdir instead.

This function returns a NULL-terminated array of strings (like environ(3)), or NULL if there was an error. The caller must free the strings and the array after use.

guestfs_lstat

struct guestfs_stat *guestfs_lstat (guestfs_h *handle,
                const char *path);

Returns file information for the given path.

This is the same as guestfs_stat except that if path is a symbolic link, then the link is stat-ed, not the file it refers to.

This is the same as the lstat(2) system call.

This function returns a struct guestfs_stat * (see stat(2) and <guestfs-structs.h>), or NULL if there was an error. The caller must call free after use.

guestfs_lvcreate

int guestfs_lvcreate (guestfs_h *handle,
                const char *logvol,
                const char *volgroup,
                int mbytes);

This creates an LVM volume group called logvol on the volume group volgroup, with size megabytes.

This function returns 0 on success or -1 on error.

guestfs_lvm_remove_all

int guestfs_lvm_remove_all (guestfs_h *handle);

This command removes all LVM logical volumes, volume groups and physical volumes.

This function returns 0 on success or -1 on error.

This command is dangerous. Without careful use you can easily destroy all your data.

guestfs_lvremove

int guestfs_lvremove (guestfs_h *handle,
                const char *device);

Remove an LVM logical volume device, where device is the path to the LV, such as /dev/VG/LV.

You can also remove all LVs in a volume group by specifying the VG name, /dev/VG.

This function returns 0 on success or -1 on error.

guestfs_lvs

char **guestfs_lvs (guestfs_h *handle);

List all the logical volumes detected. This is the equivalent of the lvs(8) command.

This returns a list of the logical volume device names (eg. /dev/VolGroup00/LogVol00).

guestfs_lvs_full

struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);

List all the logical volumes detected. This is the equivalent of the lvs(8) command. The "full" version includes all fields.

This function returns a struct guestfs_lvm_lv_list * (see <guestfs-structs.h>), or NULL if there was an error. The caller must call guestfs_free_lvm_lv_list after use.

guestfs_mkdir

int guestfs_mkdir (guestfs_h *handle,
                const char *path);

Create a directory named path.

This function returns 0 on success or -1 on error.

guestfs_mkdir_p

int guestfs_mkdir_p (guestfs_h *handle,
                const char *path);

Create a directory named path, creating any parent directories as necessary. This is like the mkdir -p shell command.

This function returns 0 on success or -1 on error.

guestfs_mkfs

int guestfs_mkfs (guestfs_h *handle,
                const char *fstype,
                const char *device);

This creates a filesystem on device (usually a partition of LVM logical volume). The filesystem type is fstype, for example ext3.

This function returns 0 on success or -1 on error.

guestfs_mount

int guestfs_mount (guestfs_h *handle,
                const char *device,
                const char *mountpoint);

Mount a guest disk at a position in the filesystem. Block devices are named /dev/sda, /dev/sdb and so on, as they were added to the guest. If those block devices contain partitions, they will have the usual names (eg. /dev/sda1). Also LVM /dev/VG/LV-style names can be used.

The rules are the same as for mount(2): A filesystem must first be mounted on / before others can be mounted. Other filesystems can only be mounted on directories which already exist.

The mounted filesystem is writable, if we have sufficient permissions on the underlying device.

The filesystem options sync and noatime are set with this call, in order to improve reliability.

This function returns 0 on success or -1 on error.

guestfs_mount_options

int guestfs_mount_options (guestfs_h *handle,
                const char *options,
                const char *device,
                const char *mountpoint);

This is the same as the guestfs_mount command, but it allows you to set the mount options as for the mount(8) -o flag.

This function returns 0 on success or -1 on error.

guestfs_mount_ro

int guestfs_mount_ro (guestfs_h *handle,
                const char *device,
                const char *mountpoint);

This is the same as the guestfs_mount command, but it mounts the filesystem with the read-only (-o ro) flag.

This function returns 0 on success or -1 on error.

guestfs_mount_vfs

int guestfs_mount_vfs (guestfs_h *handle,
                const char *options,
                const char *vfstype,
                const char *device,
                const char *mountpoint);

This is the same as the guestfs_mount command, but it allows you to set both the mount options and the vfstype as for the mount(8) -o and -t flags.

This function returns 0 on success or -1 on error.

guestfs_mounts

char **guestfs_mounts (guestfs_h *handle);

This returns the list of currently mounted filesystems. It returns the list of devices (eg. /dev/sda1, /dev/VG/LV).

Some internal mounts are not shown.

This function returns a NULL-terminated array of strings (like environ(3)), or NULL if there was an error. The caller must free the strings and the array after use.

guestfs_pvcreate

int guestfs_pvcreate (guestfs_h *handle,
                const char *device);

This creates an LVM physical volume on the named device, where device should usually be a partition name such as /dev/sda1.

This function returns 0 on success or -1 on error.

guestfs_pvremove

int guestfs_pvremove (guestfs_h *handle,
                const char *device);

This wipes a physical volume device so that LVM will no longer recognise it.

The implementation uses the pvremove command which refuses to wipe physical volumes that contain any volume groups, so you have to remove those first.

This function returns 0 on success or -1 on error.

guestfs_pvs

char **guestfs_pvs (guestfs_h *handle);

List all the physical volumes detected. This is the equivalent of the pvs(8) command.

This returns a list of just the device names that contain PVs (eg. /dev/sda2).

guestfs_pvs_full

struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);

List all the physical volumes detected. This is the equivalent of the pvs(8) command. The "full" version includes all fields.

This function returns a struct guestfs_lvm_pv_list * (see <guestfs-structs.h>), or NULL if there was an error. The caller must call guestfs_free_lvm_pv_list after use.

guestfs_read_lines

char **guestfs_read_lines (guestfs_h *handle,
                const char *path);

Return the contents of the file named path.

The file contents are returned as a list of lines. Trailing LF and CRLF character sequences are not returned.

Note that this function cannot correctly handle binary files (specifically, files containing \0 character which is treated as end of line). For those you need to use the guestfs_read_file function which has a more complex interface.

This function returns a NULL-terminated array of strings (like environ(3)), or NULL if there was an error. The caller must free the strings and the array after use.

guestfs_rm

int guestfs_rm (guestfs_h *handle,
                const char *path);

Remove the single file path.

This function returns 0 on success or -1 on error.

guestfs_rm_rf

int guestfs_rm_rf (guestfs_h *handle,
                const char *path);

Remove the file or directory path, recursively removing the contents if its a directory. This is like the rm -rf shell command.

This function returns 0 on success or -1 on error.

guestfs_rmdir

int guestfs_rmdir (guestfs_h *handle,
                const char *path);

Remove the single directory path.

This function returns 0 on success or -1 on error.

guestfs_set_autosync

int guestfs_set_autosync (guestfs_h *handle,
                int autosync);

If autosync is true, this enables autosync. Libguestfs will make a best effort attempt to run guestfs_umount_all followed by guestfs_sync when the handle is closed (also if the program exits without closing handles).

This is disabled by default (except in guestfish where it is enabled by default).

This function returns 0 on success or -1 on error.

guestfs_set_busy

int guestfs_set_busy (guestfs_h *handle);

This sets the state to BUSY. This is only used when implementing actions using the low-level API.

For more information on states, see guestfs(3).

This function returns 0 on success or -1 on error.

guestfs_set_e2label

int guestfs_set_e2label (guestfs_h *handle,
                const char *device,
                const char *label);

This sets the ext2/3/4 filesystem label of the filesystem on device to label. Filesystem labels are limited to 16 characters.

You can use either guestfs_tune2fs_l or guestfs_get_e2label to return the existing label on a filesystem.

This function returns 0 on success or -1 on error.

guestfs_set_e2uuid

int guestfs_set_e2uuid (guestfs_h *handle,
                const char *device,
                const char *uuid);

This sets the ext2/3/4 filesystem UUID of the filesystem on device to uuid. The format of the UUID and alternatives such as clear, random and time are described in the tune2fs(8) manpage.

You can use either guestfs_tune2fs_l or guestfs_get_e2uuid to return the existing UUID of a filesystem.

This function returns 0 on success or -1 on error.

guestfs_set_path

int guestfs_set_path (guestfs_h *handle,
                const char *path);

Set the path that libguestfs searches for kernel and initrd.img.

The default is $libdir/guestfs unless overridden by setting LIBGUESTFS_PATH environment variable.

The string path is stashed in the libguestfs handle, so the caller must make sure it remains valid for the lifetime of the handle.

Setting path to NULL restores the default path.

This function returns 0 on success or -1 on error.

guestfs_set_qemu

int guestfs_set_qemu (guestfs_h *handle,
                const char *qemu);

Set the qemu binary that we will use.

The default is chosen when the library was compiled by the configure script.

You can also override this by setting the LIBGUESTFS_QEMU environment variable.

The string qemu is stashed in the libguestfs handle, so the caller must make sure it remains valid for the lifetime of the handle.

Setting qemu to NULL restores the default qemu binary.

This function returns 0 on success or -1 on error.

guestfs_set_ready

int guestfs_set_ready (guestfs_h *handle);

This sets the state to READY. This is only used when implementing actions using the low-level API.

For more information on states, see guestfs(3).

This function returns 0 on success or -1 on error.

guestfs_set_verbose

int guestfs_set_verbose (guestfs_h *handle,
                int verbose);

If verbose is true, this turns on verbose messages (to stderr).

Verbose messages are disabled unless the environment variable LIBGUESTFS_DEBUG is defined and set to 1.

This function returns 0 on success or -1 on error.

guestfs_sfdisk

int guestfs_sfdisk (guestfs_h *handle,
                const char *device,
                int cyls,
                int heads,
                int sectors,
                char * const* const lines);

This is a direct interface to the sfdisk(8) program for creating partitions on block devices.

device should be a block device, for example /dev/sda.

cyls, heads and sectors are the number of cylinders, heads and sectors on the device, which are passed directly to sfdisk as the -C, -H and -S parameters. If you pass 0 for any of these, then the corresponding parameter is omitted. Usually for 'large' disks, you can just pass 0 for these, but for small (floppy-sized) disks, sfdisk (or rather, the kernel) cannot work out the right geometry and you will need to tell it.

lines is a list of lines that we feed to sfdisk. For more information refer to the sfdisk(8) manpage.

To create a single partition occupying the whole disk, you would pass lines as a single element list, when the single element being the string , (comma).

This function returns 0 on success or -1 on error.

This command is dangerous. Without careful use you can easily destroy all your data.

guestfs_stat

struct guestfs_stat *guestfs_stat (guestfs_h *handle,
                const char *path);

Returns file information for the given path.

This is the same as the stat(2) system call.

This function returns a struct guestfs_stat * (see stat(2) and <guestfs-structs.h>), or NULL if there was an error. The caller must call free after use.

guestfs_statvfs

struct guestfs_statvfs *guestfs_statvfs (guestfs_h *handle,
                const char *path);

Returns file system statistics for any mounted file system. path should be a file or directory in the mounted file system (typically it is the mount point itself, but it doesn't need to be).

This is the same as the statvfs(2) system call.

This function returns a struct guestfs_statvfs * (see statvfs(2) and <guestfs-structs.h>), or NULL if there was an error. The caller must call free after use.

guestfs_sync

int guestfs_sync (guestfs_h *handle);

This syncs the disk, so that any writes are flushed through to the underlying disk image.

You should always call this if you have modified a disk image, before closing the handle.

This function returns 0 on success or -1 on error.

guestfs_tar_in

int guestfs_tar_in (guestfs_h *handle,
                const char *tarfile,
                const char *directory);

This command uploads and unpacks local file tarfile (an uncompressed tar file) into directory.

To upload a compressed tarball, use guestfs_tgz_in.

This function returns 0 on success or -1 on error.

guestfs_tar_out

int guestfs_tar_out (guestfs_h *handle,
                const char *directory,
                const char *tarfile);

This command packs the contents of directory and downloads it to local file tarfile.

To download a compressed tarball, use guestfs_tgz_out.

This function returns 0 on success or -1 on error.

guestfs_tgz_in

int guestfs_tgz_in (guestfs_h *handle,
                const char *tarball,
                const char *directory);

This command uploads and unpacks local file tarball (a gzip compressed tar file) into directory.

To upload an uncompressed tarball, use guestfs_tar_in.

This function returns 0 on success or -1 on error.

guestfs_tgz_out

int guestfs_tgz_out (guestfs_h *handle,
                const char *directory,
                const char *tarball);

This command packs the contents of directory and downloads it to local file tarball.

To download an uncompressed tarball, use guestfs_tar_out.

This function returns 0 on success or -1 on error.

guestfs_touch

int guestfs_touch (guestfs_h *handle,
                const char *path);

Touch acts like the touch(1) command. It can be used to update the timestamps on a file, or, if the file does not exist, to create a new zero-length file.

This function returns 0 on success or -1 on error.

guestfs_tune2fs_l

char **guestfs_tune2fs_l (guestfs_h *handle,
                const char *device);

This returns the contents of the ext2, ext3 or ext4 filesystem superblock on device.

It is the same as running tune2fs -l device. See tune2fs(8) manpage for more details. The list of fields returned isn't clearly defined, and depends on both the version of tune2fs that libguestfs was built against, and the filesystem itself.

This function returns a NULL-terminated array of strings, or NULL if there was an error. The array of strings will always have length 2n+1, where n keys and values alternate, followed by the trailing NULL entry. The caller must free the strings and the array after use.

guestfs_umount

int guestfs_umount (guestfs_h *handle,
                const char *pathordevice);

This unmounts the given filesystem. The filesystem may be specified either by its mountpoint (path) or the device which contains the filesystem.

This function returns 0 on success or -1 on error.

guestfs_umount_all

int guestfs_umount_all (guestfs_h *handle);

This unmounts all mounted filesystems.

Some internal mounts are not unmounted by this call.

This function returns 0 on success or -1 on error.

guestfs_upload

int guestfs_upload (guestfs_h *handle,
                const char *filename,
                const char *remotefilename);

Upload local file filename to remotefilename on the filesystem.

filename can also be a named pipe.

guestfs_vgcreate

int guestfs_vgcreate (guestfs_h *handle,
                const char *volgroup,
                char * const* const physvols);

This creates an LVM volume group called volgroup from the non-empty list of physical volumes physvols.

This function returns 0 on success or -1 on error.

guestfs_vgremove

int guestfs_vgremove (guestfs_h *handle,
                const char *vgname);

Remove an LVM volume group vgname, (for example VG).

This also forcibly removes all logical volumes in the volume group (if any).

This function returns 0 on success or -1 on error.

guestfs_vgs

char **guestfs_vgs (guestfs_h *handle);

List all the volumes groups detected. This is the equivalent of the vgs(8) command.

This returns a list of just the volume group names that were detected (eg. VolGroup00).

guestfs_vgs_full

struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);

List all the volumes groups detected. This is the equivalent of the vgs(8) command. The "full" version includes all fields.

This function returns a struct guestfs_lvm_vg_list * (see <guestfs-structs.h>), or NULL if there was an error. The caller must call guestfs_free_lvm_vg_list after use.

guestfs_wait_ready

int guestfs_wait_ready (guestfs_h *handle);

Internally libguestfs is implemented by running a virtual machine using qemu(1).

You should call this after guestfs_launch to wait for the launch to complete.

This function returns 0 on success or -1 on error.

guestfs_write_file

int guestfs_write_file (guestfs_h *handle,
                const char *path,
                const char *content,
                int size);

This call creates a file called path. The contents of the file is the string content (which can contain any 8 bit data), with length size.

As a special case, if size is 0 then the length is calculated using strlen (so in this case the content cannot contain embedded ASCII NULs).

This function returns 0 on success or -1 on error.

Because of the message protocol, there is a transfer limit of somewhere between 2MB and 4MB. To transfer large files you should use FTP.

guestfs_zero

int guestfs_zero (guestfs_h *handle,
                const char *device);

This command writes zeroes over the first few blocks of device.

How many blocks are zeroed isn't specified (but it's not enough to securely wipe the device). It should be sufficient to remove any partition tables, filesystem superblocks and so on.

This function returns 0 on success or -1 on error.

Files

guestfs-actions.pod

Latest commit

History

guestfs-actions.pod

File metadata and controls

guestfs_add_cdrom

guestfs_add_drive

guestfs_aug_close

guestfs_aug_defnode

guestfs_aug_defvar

guestfs_aug_get

guestfs_aug_init

guestfs_aug_insert

guestfs_aug_load

guestfs_aug_ls

guestfs_aug_match

guestfs_aug_mv

guestfs_aug_rm

guestfs_aug_save

guestfs_aug_set

guestfs_blockdev_flushbufs

guestfs_blockdev_getbsz

guestfs_blockdev_getro

guestfs_blockdev_getsize64

guestfs_blockdev_getss

guestfs_blockdev_getsz

guestfs_blockdev_rereadpt

guestfs_blockdev_setbsz

guestfs_blockdev_setro

guestfs_blockdev_setrw

guestfs_cat

guestfs_checksum

guestfs_chmod

guestfs_chown

guestfs_command

guestfs_command_lines

guestfs_config

guestfs_debug

guestfs_download

guestfs_exists

guestfs_file

guestfs_fsck

guestfs_get_autosync

guestfs_get_e2label

guestfs_get_e2uuid

guestfs_get_path

guestfs_get_qemu

guestfs_get_state

guestfs_get_verbose

guestfs_is_busy

guestfs_is_config

guestfs_is_dir

guestfs_is_file

guestfs_is_launching

guestfs_is_ready

guestfs_kill_subprocess

guestfs_launch

guestfs_list_devices

guestfs_list_partitions

guestfs_ll

guestfs_ls

guestfs_lstat

guestfs_lvcreate

guestfs_lvm_remove_all

guestfs_lvremove

guestfs_lvs

guestfs_lvs_full

guestfs_mkdir

guestfs_mkdir_p

guestfs_mkfs

guestfs_mount

guestfs_mount_options

guestfs_mount_ro

guestfs_mount_vfs

guestfs_mounts

guestfs_pvcreate

guestfs_pvremove

guestfs_pvs

guestfs_pvs_full