guestfs-actions.pod

   1 =head2 guestfs_cat
   2
   3  char *guestfs_cat (guestfs_h *handle,
   4                 const char *path);
   5
   6 Return the contents of the file named C<path>.
   7
   8 Note that this function cannot correctly handle binary files
   9 (specifically, files containing C<\0> character which is treated
  10 as end of string).  For those you need to use the C<guestfs_read_file>
  11 function which has a more complex interface.
  12
  13 This function returns a string or NULL on error.
  14 I<The caller must free the returned string after use>.
  15
  16 Because of the message protocol, there is a transfer limit
  17 of somewhere between 2MB and 4MB.  To transfer large files you should use
  18 FTP.
  19
  20 =head2 guestfs_list_devices
  21
  22  char **guestfs_list_devices (guestfs_h *handle);
  23
  24 List all the block devices.
  25
  26 The full block device names are returned, eg. C</dev/sda>
  27
  28
  29 This function returns a NULL-terminated array of strings
  30 (like L<environ(3)>), or NULL if there was an error.
  31 I<The caller must free the strings and the array after use>.
  32
  33 =head2 guestfs_list_partitions
  34
  35  char **guestfs_list_partitions (guestfs_h *handle);
  36
  37 List all the partitions detected on all block devices.
  38
  39 The full partition device names are returned, eg. C</dev/sda1>
  40
  41 This does not return logical volumes.  For that you will need to
  42 call C<guestfs_lvs>.
  43
  44 This function returns a NULL-terminated array of strings
  45 (like L<environ(3)>), or NULL if there was an error.
  46 I<The caller must free the strings and the array after use>.
  47
  48 =head2 guestfs_ll
  49
  50  char *guestfs_ll (guestfs_h *handle,
  51                 const char *directory);
  52
  53 List the files in C<directory> (relative to the root directory,
  54 there is no cwd) in the format of 'ls -la'.
  55
  56 This command is mostly useful for interactive sessions.  It
  57 is I<not> intended that you try to parse the output string.
  58
  59 This function returns a string or NULL on error.
  60 I<The caller must free the returned string after use>.
  61
  62 =head2 guestfs_ls
  63
  64  char **guestfs_ls (guestfs_h *handle,
  65                 const char *directory);
  66
  67 List the files in C<directory> (relative to the root directory,
  68 there is no cwd).  The '.' and '..' entries are not returned, but
  69 hidden files are shown.
  70
  71 This command is mostly useful for interactive sessions.  Programs
  72 should probably use C<guestfs_readdir> instead.
  73
  74 This function returns a NULL-terminated array of strings
  75 (like L<environ(3)>), or NULL if there was an error.
  76 I<The caller must free the strings and the array after use>.
  77
  78 =head2 guestfs_lvs
  79
  80  char **guestfs_lvs (guestfs_h *handle);
  81
  82 List all the logical volumes detected.  This is the equivalent
  83 of the L<lvs(8)> command.
  84
  85 This returns a list of the logical volume device names
  86 (eg. C</dev/VolGroup00/LogVol00>).
  87
  88 See also C<guestfs_lvs_full>.
  89
  90 This function returns a NULL-terminated array of strings
  91 (like L<environ(3)>), or NULL if there was an error.
  92 I<The caller must free the strings and the array after use>.
  93
  94 =head2 guestfs_lvs_full
  95
  96  struct guestfs_lvm_lv_list *guestfs_lvs_full (guestfs_h *handle);
  97
  98 List all the logical volumes detected.  This is the equivalent
  99 of the L<lvs(8)> command.  The "full" version includes all fields.
 100
 101 This function returns a C<struct guestfs_lvm_lv_list>.
 102 I<The caller must call C<guestfs_free_lvm_lv_list> after use.>.
 103
 104 =head2 guestfs_mount
 105
 106  int guestfs_mount (guestfs_h *handle,
 107                 const char *device,
 108                 const char *mountpoint);
 109
 110 Mount a guest disk at a position in the filesystem.  Block devices
 111 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
 112 the guest.  If those block devices contain partitions, they will have
 113 the usual names (eg. C</dev/sda1>).  Also LVM C</dev/VG/LV>-style
 114 names can be used.
 115
 116 The rules are the same as for L<mount(2)>:  A filesystem must
 117 first be mounted on C</> before others can be mounted.  Other
 118 filesystems can only be mounted on directories which already
 119 exist.
 120
 121 The mounted filesystem is writable, if we have sufficient permissions
 122 on the underlying device.
 123
 124 The filesystem options C<sync> and C<noatime> are set with this
 125 call, in order to improve reliability.
 126
 127 This function returns 0 on success or -1 on error.
 128
 129 =head2 guestfs_pvs
 130
 131  char **guestfs_pvs (guestfs_h *handle);
 132
 133 List all the physical volumes detected.  This is the equivalent
 134 of the L<pvs(8)> command.
 135
 136 This returns a list of just the device names that contain
 137 PVs (eg. C</dev/sda2>).
 138
 139 See also C<guestfs_pvs_full>.
 140
 141 This function returns a NULL-terminated array of strings
 142 (like L<environ(3)>), or NULL if there was an error.
 143 I<The caller must free the strings and the array after use>.
 144
 145 =head2 guestfs_pvs_full
 146
 147  struct guestfs_lvm_pv_list *guestfs_pvs_full (guestfs_h *handle);
 148
 149 List all the physical volumes detected.  This is the equivalent
 150 of the L<pvs(8)> command.  The "full" version includes all fields.
 151
 152 This function returns a C<struct guestfs_lvm_pv_list>.
 153 I<The caller must call C<guestfs_free_lvm_pv_list> after use.>.
 154
 155 =head2 guestfs_sync
 156
 157  int guestfs_sync (guestfs_h *handle);
 158
 159 This syncs the disk, so that any writes are flushed through to the
 160 underlying disk image.
 161
 162 You should always call this if you have modified a disk image, before
 163 calling C<guestfs_close>.
 164
 165 This function returns 0 on success or -1 on error.
 166
 167 =head2 guestfs_touch
 168
 169  int guestfs_touch (guestfs_h *handle,
 170                 const char *path);
 171
 172 Touch acts like the L<touch(1)> command.  It can be used to
 173 update the timestamps on a file, or, if the file does not exist,
 174 to create a new zero-length file.
 175
 176 This function returns 0 on success or -1 on error.
 177
 178 =head2 guestfs_vgs
 179
 180  char **guestfs_vgs (guestfs_h *handle);
 181
 182 List all the volumes groups detected.  This is the equivalent
 183 of the L<vgs(8)> command.
 184
 185 This returns a list of just the volume group names that were
 186 detected (eg. C<VolGroup00>).
 187
 188 See also C<guestfs_vgs_full>.
 189
 190 This function returns a NULL-terminated array of strings
 191 (like L<environ(3)>), or NULL if there was an error.
 192 I<The caller must free the strings and the array after use>.
 193
 194 =head2 guestfs_vgs_full
 195
 196  struct guestfs_lvm_vg_list *guestfs_vgs_full (guestfs_h *handle);
 197
 198 List all the volumes groups detected.  This is the equivalent
 199 of the L<vgs(8)> command.  The "full" version includes all fields.
 200
 201 This function returns a C<struct guestfs_lvm_vg_list>.
 202 I<The caller must call C<guestfs_free_lvm_vg_list> after use.>.
 203