mirrors/libguestfs
1
0
Fork 0
mirror of https://github.com/libguestfs/libguestfs.git synced 2026-03-21 22:53:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add internal documentation for a few daemon functions.

Browse Source
This commit is contained in:
Richard W.M. Jones
2016-04-12 20:59:40 +01:00
parent 4d55b046e3
commit 82aa5bd25e
3 changed files with 162 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
daemon/command.c
View File

@@ -16,6 +16,11 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
/**
* This file contains a number of useful functions for running
* external commands and capturing their output.
*/
#include <config.h>
#include <stdio.h>
@@ -44,8 +49,16 @@ extern size_t sysroot_len;
#define PIPE_READ 0
#define PIPE_WRITE 1
/* Easy ways to run external commands. For full documentation, see
* 'commandrvf' below.
/**
* Run a command. Optionally capture stdout and stderr as strings.
*
* Returns C<0> if the command ran successfully, or C<-1> if there was
* any error.
*
* For a description of the C<flags> see C<commandrvf>.
*
* There is also a macro C<command(out,err,name,...)> which calls
* C<commandf> with C<flags=0>.
*/
int
commandf (char **stdoutput, char **stderror, unsigned flags,
@@ -89,9 +102,14 @@ commandf (char **stdoutput, char **stderror, unsigned flags,
return r;
}
/* Same as 'command', but we allow the status code from the
/**
* Same as C<command>, but we allow the status code from the
* subcommand to be non-zero, and return that status code.
* We still return -1 if there was some other error.
*
* We still return C<-1> if there was some other error.
*
* There is also a macro C<commandr(out,err,name,...)> which calls
* C<commandrf> with C<flags=0>.
*/
int
commandrf (char **stdoutput, char **stderror, unsigned flags,
@@ -133,7 +151,12 @@ commandrf (char **stdoutput, char **stderror, unsigned flags,
return r;
}
/* Same as 'command', but passing an argv. */
/**
* Same as C<command>, but passing in an argv array.
*
* There is also a macro C<commandv(out,err,argv)> which calls
* C<commandvf> with C<flags=0>.
*/
int
commandvf (char **stdoutput, char **stderror, unsigned flags,
char const *const *argv)
@@ -147,35 +170,46 @@ commandvf (char **stdoutput, char **stderror, unsigned flags,
return -1;
}
/* This is a more sane version of 'system(3)' for running external
/**
* This is a more sane version of L<system(3)> for running external
* commands. It uses fork/execvp, so we don't need to worry about
* quoting of parameters, and it allows us to capture any error
* messages in a buffer.
*
* If stdoutput is not NULL, then *stdoutput will return the stdout
* of the command.
* If C<stdoutput> is not C<NULL>, then C<*stdoutput> will return the
* stdout of the command as a string.
*
* If stderror is not NULL, then *stderror will return the stderr
* of the command. If there is a final \n character, it is removed
* so you can use the error string directly in a call to
* reply_with_error.
* If C<stderror> is not C<NULL>, then C<*stderror> will return the
* stderr of the command. If there is a final \n character, it is
* removed so you can use the error string directly in a call to
* C<reply_with_error>.
*
* Flags:
* Flags are:
*
* COMMAND_FLAG_FOLD_STDOUT_ON_STDERR: For broken external commands
* that send error messages to stdout (hello, parted) but that don't
* have any useful stdout information, use this flag to capture the
* error messages in the *stderror buffer. If using this flag,
* you should pass stdoutput as NULL because nothing could ever be
* captured in that buffer.
* =over 4
*
* COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN: For running external
* commands on chrooted files correctly (see RHBZ#579608) specifying
* this flag causes another process to be forked which chroots into
* sysroot and just copies the input file to stdin of the specified
* command. The file descriptor is ORed with the flags, and that file
* descriptor is always closed by this function. See hexdump.c for an
* =item C<COMMAND_FLAG_FOLD_STDOUT_ON_STDERR>
*
* For broken external commands that send error messages to stdout
* (hello, parted) but that don't have any useful stdout information,
* use this flag to capture the error messages in the C<*stderror>
* buffer. If using this flag, you should pass C<stdoutput=NULL>
* because nothing could ever be captured in that buffer.
*
* =item C<COMMAND_FLAG_CHROOT_COPY_FILE_TO_STDIN>
*
* For running external commands on chrooted files correctly (see
* L<https://bugzilla.redhat.com/579608>) specifying this flag causes
* another process to be forked which chroots into sysroot and just
* copies the input file to stdin of the specified command. The file
* descriptor is ORed with the flags, and that file descriptor is
* always closed by this function. See F<daemon/hexdump.c> for an
* example of usage.
*
* =back
*
* There is also a macro C<commandrv(out,err,argv)> which calls
* C<commandrvf> with C<flags=0>.
*/
int
commandrvf (char **stdoutput, char **stderror, unsigned flags,

150
daemon/guestfsd.c
View File

@@ -16,6 +16,12 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
/**
* This is the guestfs daemon which runs inside the guestfs appliance.
* This file handles start up, connecting back to the library, and has
* several utility functions.
*/
#include <config.h>
#ifdef HAVE_WINDOWS_H
@@ -382,7 +388,8 @@ makeraw (const char *channel, int fd)
}
}
/* Return true iff device is the root device (and therefore should be
/**
* Return true iff device is the root device (and therefore should be
* ignored from the point of view of user calls).
*/
static int
@@ -404,12 +411,14 @@ is_root_device (const char *device)
return is_root_device_stat (&statbuf);
}
/* Turn "/path" into "/sysroot/path".
/**
* Turn C<"/path"> into C<"/sysroot/path">.
*
* Caller must check for NULL and call reply_with_perror ("malloc")
* if it is. Caller must also free the string.
* Returns C<NULL> on failure. The caller I<must> check for this and
* call S<C<reply_with_perror ("malloc")>>. The caller must also free
* the returned string.
*
* See also the custom %R printf formatter which does shell quoting too.
* See also the custom C<%R> printf formatter which does shell quoting too.
*/
char *
sysroot_path (const char *path)
@@ -425,12 +434,15 @@ sysroot_path (const char *path)
return r;
}
/* Resolve path within sysroot, calling sysroot_path on the resolved path.
/**
* Resolve path within sysroot, calling C<sysroot_path> on the
* resolved path.
*
* Caller must check for NULL and call reply_with_perror ("malloc/realpath")
* if it is. Caller must also free the string.
* Returns C<NULL> on failure. The caller I<must> check for this and
* call S<C<reply_with_perror ("malloc")>>. The caller must also free
* the returned string.
*
* See also the custom %R printf formatter which does shell quoting too.
* See also the custom C<%R> printf formatter which does shell quoting too.
*/
char *
sysroot_realpath (const char *path)
@@ -584,7 +596,12 @@ count_strings (char *const *argv)
return argc;
}
/* http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2 */
/**
* Returns true if C<v> is a power of 2.
*
* Uses the algorithm described at
* L<http://graphics.stanford.edu/~seander/bithacks.html#DetermineIfPowerOf2>
*/
int
is_power_of_2 (unsigned long v)
{
@@ -631,8 +648,10 @@ free_stringslen (char **argv, size_t len)
free (argv);
}
/* Compare device names (including partition numbers if present).
* https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/
/**
* Compare device names (including partition numbers if present).
*
* L<https://rwmj.wordpress.com/2011/01/09/how-are-linux-drives-named-beyond-drive-26-devsdz/>
*/
int
compare_device_names (const char *a, const char *b)
@@ -745,26 +764,46 @@ join_strings (const char *separator, char *const *argv)
return r;
}
/* Split an output string into a NULL-terminated list of lines,
/**
* Split an output string into a NULL-terminated list of lines,
* wrapped into a stringsbuf.
*
* Typically this is used where we have run an external command
* which has printed out a list of things, and we want to return
* an actual list.
*
* The corner cases here are quite tricky. Note in particular:
*
* "" -> []
* "\n" -> [""]
* "a\nb" -> ["a"; "b"]
* "a\nb\n" -> ["a"; "b"]
* "a\nb\n\n" -> ["a"; "b"; ""]
* =over 4
*
* The original string is written over and destroyed by this
* function (which is usually OK because it's the 'out' string
* from command()). You can free the original string, because
* add_string() strdups the strings.
* =item C<"">
*
* argv in the stringsbuf will be NULL in case of errors.
* returns C<[]>
*
* =item C<"\n">
*
* returns C<[""]>
*
* =item C<"a\nb">
*
* returns C<["a"; "b"]>
*
* =item C<"a\nb\n">
*
* returns C<["a"; "b"]>
*
* =item C<"a\nb\n\n">
*
* returns C<["a"; "b"; ""]>
*
* =back
*
* The original string is written over and destroyed by this function
* (which is usually OK because it's the 'out' string from
* C<command*()>). You can free the original string, because
* C<add_string()> strdups the strings.
*
* C<argv> in the C<struct stringsbuf> will be C<NULL> in case of errors.
*/
struct stringsbuf
split_lines_sb (char *str)
@@ -827,7 +866,8 @@ empty_list (void)
return ret.argv;
}
/* Skip leading and trailing whitespace, updating the original string
/**
* Skip leading and trailing whitespace, updating the original string
* in-place.
*/
void
@@ -849,8 +889,9 @@ trim (char *str)
memmove (str, p, len+1);
}
/* printf helper function so we can use %Q ("quoted") and %R to print
* shell-quoted strings. See guestfs-hacking(1) for more
/**
* printf helper function so we can use C<%Q> ("quoted") and C<%R> to
* print shell-quoted strings. See L<guestfs-hacking(1)> for more
* details.
*/
static int
@@ -909,15 +950,17 @@ print_arginfo (const struct printf_info *info, size_t n, int *argtypes)
#endif
#endif
/* Perform device name translation. See guestfs(3) for the algorithm.
* Usually you should not call this directly.
/**
* Perform device name translation. See L<guestfs(3)> for the
* algorithm. Usually you should not call this directly.
*
* It returns a newly allocated string which the caller must free.
*
* It returns NULL on error. *Note* it does *NOT* call reply_with_*.
* It returns C<NULL> on error. B<Note> it does I<not> call
* C<reply_with_*>.
*
* We have to open the device and test for ENXIO, because the device
* nodes may exist in the appliance.
* We have to open the device and test for C<ENXIO>, because the
* device nodes may exist in the appliance.
*/
char *
device_name_translation (const char *device)
@@ -972,19 +1015,20 @@ device_name_translation (const char *device)
return NULL;
}
/* Parse the mountable descriptor for a btrfs subvolume. Don't call
/**
* Parse the mountable descriptor for a btrfs subvolume. Don't call
* this directly; it is only used from the stubs.
*
* A btrfs subvolume is given as:
*
* btrfsvol:/dev/sda3/root
* btrfsvol:/dev/sda3/root
*
* where /dev/sda3 is a block device containing a btrfs filesystem,
* where F</dev/sda3> is a block device containing a btrfs filesystem,
* and root is the name of a subvolume on it. This function is passed
* the string following 'btrfsvol:'.
* the string following C<"btrfsvol:">.
*
* On success, mountable->device & mountable->volume must be freed by
* the caller.
* On success, C<mountable-E<gt>device> and C<mountable-E<gt>volume>
* must be freed by the caller.
*/
int
parse_btrfsvol (const char *desc_orig, mountable_t *mountable)
@@ -1047,10 +1091,11 @@ parse_btrfsvol (const char *desc_orig, mountable_t *mountable)
return 0;
}
/* Convert a mountable_t back to its string representation
/**
* Convert a C<mountable_t> back to its string representation
*
* This function can be used in an error path, and must not call
* reply_with_error().
* This function can be used in an error path, so must not call
* C<reply_with_error>.
*/
char *
mountable_to_string (const mountable_t *mountable)
@@ -1078,7 +1123,9 @@ mountable_to_string (const mountable_t *mountable)
#pragma GCC diagnostic ignored "-Wstack-usage="
#endif
/* Check program exists and is executable on $PATH. */
/**
* Check program exists and is executable on C<$PATH>.
*/
int
prog_exists (const char *prog)
{
@@ -1114,9 +1161,11 @@ prog_exists (const char *prog)
#pragma GCC diagnostic pop
#endif
/* Pass a template such as "/sysroot/XXXXXXXX.XXX". This updates the
* template to contain a randomly named file. Any 'X' characters
* after the final '/' are replaced with random characters.
/**
* Pass a template such as C<"/sysroot/XXXXXXXX.XXX">. This updates
* the template to contain a randomly named file. Any C<'X'>
* characters after the final C<'/'> in the template are replaced with
* random characters.
*
* Notes: You should probably use an 8.3 path, so it's compatible with
* all filesystems including basic FAT. Also this only substitutes
@@ -1127,7 +1176,7 @@ prog_exists (const char *prog)
* (it would be extremely unlikely to exist as long as the RNG is
* working).
*
* If there is an error, -1 is returned.
* If there is an error, C<-1> is returned.
*/
int
random_name (char *template)
@@ -1160,12 +1209,13 @@ random_name (char *template)
return 0;
}
/* LVM and other commands aren't synchronous, especially when udev is
* involved. eg. You can create or remove some device, but the /dev
* device node won't appear until some time later. This means that
* you get an error if you run one command followed by another.
/**
* LVM and other commands aren't synchronous, especially when udev is
* involved. eg. You can create or remove some device, but the
* C</dev> device node won't appear until some time later. This means
* that you get an error if you run one command followed by another.
*
* Use 'udevadm settle' after certain commands, but don't be too
* Use C<udevadm settle> after certain commands, but don't be too
* fussed if it fails.
*/
void

4
daemon/internal.c
View File

@@ -16,7 +16,9 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
/* Internal functions are not part of the public API. */
/**
* Internal functions that are not part of the public API.
*/
#include <config.h>