diff --git a/daemon/command.c b/daemon/command.c index 2423a4ef7..01df28ac7 100644 --- a/daemon/command.c +++ b/daemon/command.c @@ -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 #include @@ -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 see C. + * + * There is also a macro C which calls + * C with C. */ 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, 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 which calls + * C with C. */ 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, but passing in an argv array. + * + * There is also a macro C which calls + * C with C. + */ 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 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 is not C, 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 is not C, 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. * - * 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 + * + * 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 + * because nothing could ever be captured in that buffer. + * + * =item C + * + * For running external commands on chrooted files correctly (see + * L) 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 for an * example of usage. + * + * =back + * + * There is also a macro C which calls + * C with C. */ int commandrvf (char **stdoutput, char **stderror, unsigned flags, diff --git a/daemon/guestfsd.c b/daemon/guestfsd.c index b76b5a48a..8b9acc773 100644 --- a/daemon/guestfsd.c +++ b/daemon/guestfsd.c @@ -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 #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 on failure. The caller I check for this and + * call S>. 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 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 on failure. The caller I check for this and + * call S>. 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 is a power of 2. + * + * Uses the algorithm described at + * L + */ 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 */ 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). You can free the original string, because + * C strdups the strings. + * + * C in the C will be C 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 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 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 on error. B it does I call + * C. * - * 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, 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 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, Cdevice> and Cvolume> + * 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 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. */ 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 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 after certain commands, but don't be too * fussed if it fails. */ void diff --git a/daemon/internal.c b/daemon/internal.c index 5fb3d54c3..834fb10ab 100644 --- a/daemon/internal.c +++ b/daemon/internal.c @@ -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