1 =head2 guestfs_add_cdrom
3 int guestfs_add_cdrom (guestfs_h *handle,
6 This function adds a virtual CD-ROM disk image to the guest.
8 This is equivalent to the qemu parameter C<-cdrom filename>.
10 This function returns 0 on success or -1 on error.
12 =head2 guestfs_add_drive
14 int guestfs_add_drive (guestfs_h *handle,
15 const char *filename);
17 This function adds a virtual machine disk image C<filename> to the
18 guest. The first time you call this function, the disk appears as IDE
19 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
22 You don't necessarily need to be root when using libguestfs. However
23 you obviously do need sufficient permissions to access the filename
24 for whatever operations you want to perform (ie. read access if you
25 just want to read the image or write access if you want to modify the
28 This is equivalent to the qemu parameter C<-drive file=filename>.
30 This function returns 0 on success or -1 on error.
34 char *guestfs_cat (guestfs_h *handle,
37 Return the contents of the file named C<path>.
39 Note that this function cannot correctly handle binary files
40 (specifically, files containing C<\0> character which is treated
41 as end of string). For those you need to use the C<guestfs_read_file>
42 function which has a more complex interface.
44 This function returns a string or NULL on error.
45 I<The caller must free the returned string after use>.
47 Because of the message protocol, there is a transfer limit
48 of somewhere between 2MB and 4MB. To transfer large files you should use
53 int guestfs_config (guestfs_h *handle,
54 const char *qemuparam,
55 const char *qemuvalue);
57 This can be used to add arbitrary qemu command line parameters
58 of the form C<-param value>. Actually it's not quite arbitrary - we
59 prevent you from setting some parameters which would interfere with
60 parameters that we use.
62 The first character of C<param> string must be a C<-> (dash).
66 This function returns 0 on success or -1 on error.
68 =head2 guestfs_get_autosync
70 int guestfs_get_autosync (guestfs_h *handle);
72 Get the autosync flag.
74 This function returns a C truth value on success or -1 on error.
76 =head2 guestfs_get_path
78 const char *guestfs_get_path (guestfs_h *handle);
80 Return the current search path.
82 This is always non-NULL. If it wasn't set already, then this will
83 return the default path.
85 This function returns a string or NULL on error.
86 The string is owned by the guest handle and must I<not> be freed.
88 =head2 guestfs_get_verbose
90 int guestfs_get_verbose (guestfs_h *handle);
92 This returns the verbose messages flag.
94 This function returns a C truth value on success or -1 on error.
96 =head2 guestfs_kill_subprocess
98 int guestfs_kill_subprocess (guestfs_h *handle);
100 This kills the qemu subprocess. You should never need to call this.
102 This function returns 0 on success or -1 on error.
104 =head2 guestfs_launch
106 int guestfs_launch (guestfs_h *handle);
108 Internally libguestfs is implemented by running a virtual machine
111 You should call this after configuring the handle
112 (eg. adding drives) but before performing any actions.
114 This function returns 0 on success or -1 on error.
116 =head2 guestfs_list_devices
118 char **guestfs_list_devices (guestfs_h *handle);
120 List all the block devices.
122 The full block device names are returned, eg. C</dev/sda>
124 This function returns a NULL-terminated array of strings
125 (like L<environ(3)>), or NULL if there was an error.
126 I<The caller must free the strings and the array after use>.
128 =head2 guestfs_list_partitions
130 char **guestfs_list_partitions (guestfs_h *handle);
132 List all the partitions detected on all block devices.
134 The full partition device names are returned, eg. C</dev/sda1>
136 This does not return logical volumes. For that you will need to
139 This function returns a NULL-terminated array of strings
140 (like L<environ(3)>), or NULL if there was an error.
141 I<The caller must free the strings and the array after use>.
145 char *guestfs_ll (guestfs_h *handle,
146 const char *directory);
148 List the files in C<directory> (relative to the root directory,
149 there is no cwd) in the format of 'ls -la'.
151 This command is mostly useful for interactive sessions. It
152 is I<not> intended that you try to parse the output string.
154 This function returns a string or NULL on error.
155 I<The caller must free the returned string after use>.
159 char **guestfs_ls (guestfs_h *handle,
160 const char *directory);
162 List the files in C<directory> (relative to the root directory,
163 there is no cwd). The '.' and '..' entries are not returned, but
164 hidden files are shown.
166 This command is mostly useful for interactive sessions. Programs
167 should probably use C<guestfs_readdir> instead.
169 This function returns a NULL-terminated array of strings
170 (like L<environ(3)>), or NULL if there was an error.
171 I<The caller must free the strings and the array after use>.
175 char **guestfs_lvs (guestfs_h *handle);
177 List all the logical volumes detected. This is the equivalent
178 of the L<lvs(8)> command.
180 This returns a list of the logical volume device names
181 (eg. C</dev/VolGroup00/LogVol00>).
183 See also C<guestfs_lvs_full>.
185 This function returns a NULL-terminated array of strings
186 (like L<environ(3)>), or NULL if there was an error.
187 I<The caller must free the strings and the array after use>.
189 =head2 guestfs_lvs_full
191 struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);
193 List all the logical volumes detected. This is the equivalent
194 of the L<lvs(8)> command. The "full" version includes all fields.
196 This function returns a C<struct guestfs_lvm_lv_list>.
197 I<The caller must call C<guestfs_free_lvm_lv_list> after use.>.
201 int guestfs_mount (guestfs_h *handle,
203 const char *mountpoint);
205 Mount a guest disk at a position in the filesystem. Block devices
206 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
207 the guest. If those block devices contain partitions, they will have
208 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
211 The rules are the same as for L<mount(2)>: A filesystem must
212 first be mounted on C</> before others can be mounted. Other
213 filesystems can only be mounted on directories which already
216 The mounted filesystem is writable, if we have sufficient permissions
217 on the underlying device.
219 The filesystem options C<sync> and C<noatime> are set with this
220 call, in order to improve reliability.
222 This function returns 0 on success or -1 on error.
226 char **guestfs_pvs (guestfs_h *handle);
228 List all the physical volumes detected. This is the equivalent
229 of the L<pvs(8)> command.
231 This returns a list of just the device names that contain
232 PVs (eg. C</dev/sda2>).
234 See also C<guestfs_pvs_full>.
236 This function returns a NULL-terminated array of strings
237 (like L<environ(3)>), or NULL if there was an error.
238 I<The caller must free the strings and the array after use>.
240 =head2 guestfs_pvs_full
242 struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);
244 List all the physical volumes detected. This is the equivalent
245 of the L<pvs(8)> command. The "full" version includes all fields.
247 This function returns a C<struct guestfs_lvm_pv_list>.
248 I<The caller must call C<guestfs_free_lvm_pv_list> after use.>.
250 =head2 guestfs_set_autosync
252 int guestfs_set_autosync (guestfs_h *handle,
255 If C<autosync> is true, this enables autosync. Libguestfs will make a
256 best effort attempt to run C<guestfs_sync> when the handle is closed
257 (also if the program exits without closing handles).
259 This function returns 0 on success or -1 on error.
261 =head2 guestfs_set_path
263 int guestfs_set_path (guestfs_h *handle,
266 Set the path that libguestfs searches for kernel and initrd.img.
268 The default is C<$libdir/guestfs> unless overridden by setting
269 C<LIBGUESTFS_PATH> environment variable.
271 The string C<path> is stashed in the libguestfs handle, so the caller
272 must make sure it remains valid for the lifetime of the handle.
274 Setting C<path> to C<NULL> restores the default path.
276 This function returns 0 on success or -1 on error.
278 =head2 guestfs_set_verbose
280 int guestfs_set_verbose (guestfs_h *handle,
283 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
285 Verbose messages are disabled unless the environment variable
286 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
288 This function returns 0 on success or -1 on error.
292 int guestfs_sync (guestfs_h *handle);
294 This syncs the disk, so that any writes are flushed through to the
295 underlying disk image.
297 You should always call this if you have modified a disk image, before
300 This function returns 0 on success or -1 on error.
304 int guestfs_touch (guestfs_h *handle,
307 Touch acts like the L<touch(1)> command. It can be used to
308 update the timestamps on a file, or, if the file does not exist,
309 to create a new zero-length file.
311 This function returns 0 on success or -1 on error.
315 char **guestfs_vgs (guestfs_h *handle);
317 List all the volumes groups detected. This is the equivalent
318 of the L<vgs(8)> command.
320 This returns a list of just the volume group names that were
321 detected (eg. C<VolGroup00>).
323 See also C<guestfs_vgs_full>.
325 This function returns a NULL-terminated array of strings
326 (like L<environ(3)>), or NULL if there was an error.
327 I<The caller must free the strings and the array after use>.
329 =head2 guestfs_vgs_full
331 struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);
333 List all the volumes groups detected. This is the equivalent
334 of the L<vgs(8)> command. The "full" version includes all fields.
336 This function returns a C<struct guestfs_lvm_vg_list>.
337 I<The caller must call C<guestfs_free_lvm_vg_list> after use.>.
339 =head2 guestfs_wait_ready
341 int guestfs_wait_ready (guestfs_h *handle);
343 Internally libguestfs is implemented by running a virtual machine
346 You should call this after C<guestfs_launch> to wait for the launch
349 This function returns 0 on success or -1 on error.