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