neulab/tldr huggingface dataset:
*   unexecuted_block: flag whether the line contains an unexecuted block (not all statements on the line are executed)
*   function_name: a name of a function this line belongs to (for a line with an inlined statements can be not set)
Each branch has the following form:
{ "count": <count>, "fallthrough": <fallthrough>, "throw": <throw> }
Fields of the branch element have following semantics:
*   count: number of executions of the branch
*   fallthrough: true when the branch is a fall through branch
*   throw: true when the branch is an exceptional branch
-H --human-readable Write counts in human readable format (like 24.6k).
-k --use-colors Use colors for lines of code that have zero coverage.  We use red color for non-exceptional lines and cyan for exceptional.  Same colors are used for basic blocks with -a option.
-l --long-file-names Create long file names for included source files.  For example, if the header file x.h contains code, and was included in the file a.c, then running gcov on the file a.c will produce an output file called a.c##x.h.gcov instead of x.h.gcov.  This can be useful if x.h is included in multiple source files and you want to see the individual contributions.  If you use the -p option, both the including and included file names will be complete path names.
-m --demangled-names Display demangled function names in output. The default is to show mangled function names.
-n --no-output Do not create the gcov output file.
-o directory|file --object-directory directory --object-file file Specify either the directory containing the gcov data files, or the object path name.  The .gcno, and .gcda data files are searched for using this option.  If a directory is specified, the data files are in that directory and named after the input file name, without its extension.  If a file is specified here, the data files are named after that file, without its extension.
-p --preserve-paths Preserve complete path information in the names of generated .gcov files.  Without this option, just the filename component is used. With this option, all directories are used, with / characters translated to # characters, . directory components removed and unremoveable ..  components renamed to ^.  This is useful if sourcefiles are in several different directories.
-q --use-hotness-colors Emit perf-like colored output for hot lines.  Legend of the color scale is printed at the very beginning of the output file.
-r --relative-only Only output information about source files with a relative pathname (after source prefix elision).  Absolute paths are usually system header files and coverage of any inline functions therein is normally uninteresting.
-s directory --source-prefix directory A prefix for source file names to remove when generating the output coverage files.  This option is useful when building in a separate directory, and the pathname to the source directory is not wanted when determining the output file names.  Note that this prefix detection is applied before determining whether the source file is absolute.
-t --stdout Output to standard output instead of output files.
-u --unconditional-branches When branch probabilities are given, include those of unconditional branches.  Unconditional branches are normally not interesting.
-v --version Display the gcov version number (on the standard output), and exit without doing any further processing.
-w --verbose Print verbose informations related to basic blocks and arcs.
-x --hash-filenames When using --preserve-paths, gcov uses the full pathname of the source files to create an output filename.  This can lead to long filenames that can overflow filesystem limits.  This option creates names of the form source-file##md5.gcov, where the source-file component is the final filename part and the md5 component is calculated from the full mangled name that would have been used otherwise.  The option is an alternative to the --preserve-paths on systems which have a filesystem limit.
gcov should be run with the current directory the same as that when you invoked the compiler.  Otherwise it will not be able to locate the source files.  gcov produces files called mangledname.gcov in the current directory.  These contain the coverage information of the source file they correspond to.  One .gcov file is produced for each source (or header) file containing code, which was compiled to produce the data files.  The mangledname part of the output file name is usually simply the source file name, but can be something more complicated if the -l or -p options are given.  Refer to those options for details.
If you invoke gcov with multiple input files, the contributions from each input file are summed.  Typically you would invoke it with the same list of files as the final link of your executable.
The .gcov files contain the : separated fields along with program source code.  The format is
<execution_count>:<line_number>:<source line text>
Additional block information may succeed each line, when requested by command line option.  The execution_count is - for lines containing no code.  Unexecuted lines are marked ##### or =====, depending on whether they are reachable by non-exceptional paths or only exceptional paths such as C++ exception handlers, respectively. Given the -a option, unexecuted blocks are marked $$$$$ or %%%%%, depending on whether a basic block is reachable via non-exceptional or exceptional paths.  Executed basic blocks having a statement with zero execution_count end with * character and are colored with magenta color with the -k option.  This functionality is not supported in Ada.
Note that GCC can completely remove the bodies of functions that are not needed -- for instance if they are inlined everywhere.  Such functions are marked with -, which can be confusing.  Use the -fkeep-inline-functions and -fkeep-static-functions options to retain these functions and allow gcov to properly show their execution_count.
Some lines of information at the start have line_number of zero.  These preamble lines are of the form
-:0:<tag>:<value>
The ordering and number of these preamble lines will be augmented as gcov development progresses --- do not rely on them remaining unchanged.  Use tag to locate a particular preamble line.
The additional block information is of the form
<tag> <information>
The information is human readable, but designed to be simple enough for machine parsing too.
When printing percentages, 0% and 100% are only printed when the values are exactly 0% and 100% respectively.  Other values which would conventionally be rounded to 0% or 100% are instead printed as the nearest non-boundary value.
When using gcov, you must first compile your program with a special GCC option --coverage.  This tells the compiler to generate additional information needed by gcov (basically a flow graph of the program) and also includes additional code in the object files for generating the extra profiling information needed by gcov.  These additional files are placed in the directory where the object file is located.
Running the program will cause profile output to be generated.  For each source file compiled with -fprofile-arcs, an accompanying .gcda file will be placed in the object file directory.
Running gcov with your program's source file names as arguments will now produce a listing of the code along with frequency of execution for each line.  For example, if your program is called tmp.cpp, this is what you see when you use the basic gcov facility:
$ g++ --coverage tmp.cpp -c $ g++ --coverage tmp.o $ a.out $ gcov tmp.cpp -m File 'tmp.cpp' Lines executed:92.86% of 14 Creating 'tmp.cpp.gcov'
The file tmp.cpp.gcov contains output from gcov.  Here is a sample:
-:    0:Source:tmp.cpp -:    0:Working directory:/home/gcc/testcase -:    0:Graph:tmp.gcno -:    0:Data:tmp.gcda -:    0:Runs:1 -:    0:Programs:1 -:    1:#include <stdio.h> -:    2: -:    3:template<class T> -:    4:class Foo -:    5:{ -:    6:  public: 1*:    7:  Foo(): b (1000) {} ------------------ Foo<char>::Foo(): #####:    7:  Foo(): b (1000) {} ------------------ Foo<int>::Foo(): 1:    7:  Foo(): b (1000) {} ------------------ 2*:    8:  void inc () { b++; } ------------------ Foo<char>::inc(): #####:    8:  void inc () { b++; } ------------------ Foo<int>::inc(): 2:    8:  void inc () { b++; } ------------------ -:    9: -:   10:  private: -:   11:  int b; -:   12:}; -:   13: -:   14:template class Foo<int>; -:   15:template class Foo<char>; -:   16: -:   17:int 1:   18:main (void) -:   19:{ -:   20:  int i, total; 1:   21:  Foo<int> counter; -:   22: 1:   23:  counter.inc(); 1:   24:  counter.inc(); 1:   25:  total = 0; -:   26: 11:   27:  for (i = 0; i < 10; i++) 10:   28:    total += i; -:   29: 1*:   30:  int v = total > 100 ? 1 : 2; -:   31: 1:   32:  if (total != 45) #####:   33:    printf ("Failure\n"); -:   34:  else 1:   35:    printf ("Success\n"); 1:   36:  return 0; -:   37:}
Note that line 7 is shown in the report multiple times.  First occurrence presents total number of execution of the line and the next two belong to instances of class Foo constructors.  As you can also see, line 30 contains some unexecuted basic blocks and thus execution count has asterisk symbol.
When you use the -a option, you will get individual block counts, and the output looks like this:
-:    0:Source:tmp.cpp -:    0:Working directory:/home/gcc/testcase -:    0:Graph:tmp.gcno -:    0:Data:tmp.gcda -:    0:Runs:1 -:    0:Programs:1 -:    1:#include <stdio.h> -:    2: -:    3:template<class T> -:    4:class Foo -:    5:{ -:    6:  public: 1*:    7:  Foo(): b (1000) {} ------------------ Foo<char>::Foo(): #####:    7:  Foo(): b (1000) {} ------------------ Foo<int>::Foo(): 1:    7:  Foo(): b (1000) {} ------------------ 2*:    8:  void inc () { b++; } ------------------ Foo<char>::inc(): #####:    8:  void inc () { b++; } ------------------ Foo<int>::inc(): 2:    8:  void inc () { b++; } ------------------ -:    9: -:   10:  private: -:   11:  int b; -:   12:}; -:   13: -:   14:template class Foo<int>; -:   15:template class Foo<char>; -:   16: -:   17:int 1:   18:main (void) -:   19:{ -:   20:  int i, total; 1:   21:  Foo<int> counter; 1:   21-block  0 -:   22: 1:   23:  counter.inc(); 1:   23-block  0 1:   24:  counter.inc(); 1:   24-block  0 1:   25:  total = 0; -:   26: 11:   27:  for (i = 0; i < 10; i++) 1:   27-block  0 11:   27-block  1 10:   28:    total += i; 10:   28-block  0 -:   29: 1*:   30:  int v = total > 100 ? 1 : 2; 1:   30-block  0 %%%%%:   30-block  1 1:   30-block  2 -:   31: 1:   32:  if (total != 45) 1:   32-block  0 #####:   33:    printf ("Failure\n"); %%%%%:   33-block  0 -:   34:  else 1:   35:    printf ("Success\n"); 1:   35-block  0 1:   36:  return 0; 1:   36-block  0 -:   37:}
In this mode, each basic block is only shown on one line -- the last line of the block.  A multi-line block will only contribute to the execution count of that last line, and other lines will not be shown to contain code, unless previous blocks end on those lines.  The total execution count of a line is shown and subsequent lines show the execution counts for individual blocks that end on that line.  After each block, the branch and call counts of the block will be shown, if the -b option is given.
Because of the way GCC instruments calls, a call count can be shown after a line with no individual blocks.  As you can see, line 33 contains a basic block that was not executed.
When you use the -b option, your output looks like this:
-:    0:Source:tmp.cpp -:    0:Working directory:/home/gcc/testcase -:    0:Graph:tmp.gcno -:    0:Data:tmp.gcda -:    0:Runs:1 -:    0:Programs:1 -:    1:#include <stdio.h> -:    2: -:    3:template<class T> -:    4:class Foo -:    5:{ -:    6:  public: 1*:    7:  Foo(): b (1000) {} ------------------ Foo<char>::Foo(): function Foo<char>::Foo() called 0 returned 0% blocks executed 0% #####:    7:  Foo(): b (1000) {} ------------------ Foo<int>::Foo(): function Foo<int>::Foo() called 1 returned 100% blocks executed 100% 1:    7:  Foo(): b (1000) {} ------------------ 2*:    8:  void inc () { b++; } ------------------ Foo<char>::inc(): function Foo<char>::inc() called 0 returned 0% blocks executed 0% #####:    8:  void inc () { b++; } ------------------ Foo<int>::inc(): function Foo<int>::inc() called 2 returned 100% blocks executed 100% 2:    8:  void inc () { b++; } ------------------ -:    9: -:   10:  private: -:   11:  int b; -:   12:}; -:   13: -:   14:template class Foo<int>; -:   15:template class Foo<char>; -:   16: -:   17:int function main called 1 returned 100% blocks executed 81% 1:   18:main (void) -:   19:{ -:   20:  int i, total; 1:   21:  Foo<int> counter; call    0 returned 100% branch  1 taken 100% (fallthrough) branch  2 taken 0% (throw) -:   22: 1:   23:  counter.inc(); call    0 returned 100% branch  1 taken 100% (fallthrough) branch  2 taken 0% (throw) 1:   24:  counter.inc(); call    0 returned 100% branch  1 taken 100% (fallthrough) branch  2 taken 0% (throw) 1:   25:  total = 0; -:   26: 11:   27:  for (i = 0; i < 10; i++) branch  0 taken 91% (fallthrough) branch  1 taken 9% 10:   28:    total += i; -:   29: 1*:   30:  int v = total > 100 ? 1 : 2; branch  0 taken 0% (fallthrough) branch  1 taken 100% -:   31: 1:   32:  if (total != 45) branch  0 taken 0% (fallthrough) branch  1 taken 100% #####:   33:    printf ("Failure\n"); call    0 never executed branch  1 never executed branch  2 never executed -:   34:  else 1:   35:    printf ("Success\n"); call    0 returned 100% branch  1 taken 100% (fallthrough) branch  2 taken 0% (throw) 1:   36:  return 0; -:   37:}
For each function, a line is printed showing how many times the function is called, how many times it returns and what percentage of the function's blocks were executed.
For each basic block, a line is printed after the last line of the basic block describing the branch or call that ends the basic block.  There can be multiple branches and calls listed for a single source line if there are multiple basic blocks that end on that line.  In this case, the branches and calls are each given a number.  There is no simple way to map these branches and calls back to source constructs.  In general, though, the lowest numbered branch or call will correspond to the leftmost construct on the source line.
For a branch, if it was executed at least once, then a percentage indicating the number of times the branch was taken divided by the number of times the branch was executed will be printed.  Otherwise, the message "never executed" is printed.
For a call, if it was executed at least once, then a percentage indicating the number of times the call returned divided by the number of times the call was executed will be printed.  This will usually be 100%, but may be less for functions that call "exit" or "longjmp", and thus may not return every time they are called.
The execution counts are cumulative.  If the example program were executed again without removing the .gcda file, the count for the number of times each line in the source was executed would be added to the results of the previous run(s).  This is potentially useful in several ways.  For example, it could be used to accumulate data over a number of program runs as part of a test verification suite, or to provide more accurate long-term information over a large number of program runs.
The data in the .gcda files is saved immediately before the program exits.  For each source file compiled with -fprofile-arcs, the profiling code first attempts to read in an existing .gcda file; if the file doesn't match the executable (differing number of basic block counts) it will ignore the contents of the file.  It then adds in the new execution counts and finally writes the data to the file.
Using gcov with GCC Optimization If you plan to use gcov to help optimize your code, you must first compile your program with a special GCC option --coverage.  Aside from that, you can use any other GCC options; but if you want to prove that every single line in your program was executed, you should not compile with optimization at the same time.  On some machines the optimizer can eliminate some simple code lines by combining them with other lines.  For example, code like this:
if (a != b) c = 1; else c = 0;
can be compiled into one instruction on some machines.  In this case, there is no way for gcov to calculate separate execution counts for each line because there isn't separate code for each line.  Hence the gcov output looks like this if you compiled the program with optimization:
100:   12:if (a != b) 100:   13:  c = 1; 100:   14:else 100:   15:  c = 0;
The output shows that this block of code, combined by optimization, executed 100 times.  In one sense this result is correct, because there was only one instruction representing all four of these lines.  However, the output does not indicate how many times the result was 0 and how many times the result was 1.
Inlineable functions can create unexpected line counts.  Line counts are shown for the source code of the inlineable function, but what is shown depends on where the function is inlined, or if it is not inlined at all.
If the function is not inlined, the compiler must emit an out of line copy of the function, in any object file that needs it.  If fileA.o and fileB.o both contain out of line bodies of a particular inlineable function, they will also both contain coverage counts for that function. When fileA.o and fileB.o are linked together, the linker will, on many systems, select one of those out of line bodies for all calls to that function, and remove or ignore the other.  Unfortunately, it will not remove the coverage counters for the unused function body.  Hence when instrumented, all but one use of that function will show zero counts.
If the function is inlined in several places, the block structure in each location might not be the same.  For instance, a condition might now be calculable at compile time in some instances.  Because the coverage of all the uses of the inline function will be shown for the same source lines, the line counts themselves might seem inconsistent.
Long-running applications can use the "__gcov_reset" and "__gcov_dump" facilities to restrict profile collection to the program region of interest. Calling "__gcov_reset(void)" will clear all profile counters to zero, and calling "__gcov_dump(void)" will cause the profile information collected at that point to be dumped to .gcda output files.  Instrumented applications use a static destructor with priority 99 to invoke the "__gcov_dump" function. Thus "__gcov_dump" is executed after all user defined static destructors, as well as handlers registered with "atexit". If an executable loads a dynamic shared object via dlopen functionality, -Wl,--dynamic-list-data is needed to dump all profile data.
Profiling run-time library reports various errors related to profile manipulation and profile saving.  Errors are printed into standard error output or GCOV_ERROR_FILE file, if environment variable is used.  In order to terminate immediately after an errors occurs set GCOV_EXIT_AT_ERROR environment variable.  That can help users to find profile clashing which leads to a misleading profile.
gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for gcc.
Copyright (c) 1996-2021 Free Software Foundation, Inc.
COMMAND(1P)                 POSIX Programmer's Manual                COMMAND(1P)
command — execute a simple command
command [-p] command_name [argument...]
command [-p][-v|-V] command_name
The command utility shall cause the shell to treat the arguments as a simple command, suppressing the shell function lookup that is described in Section 2.9.1.1, Command Search and Execution, item 1b.
If the command_name is the same as the name of one of the special built- in utilities, the special properties in the enumerated list at the beginning of Section 2.14, Special Built-In Utilities shall not occur. In every other respect, if command_name is not the name of a function, the effect of command (with no options) shall be the same as omitting command.
When the -v or -V option is used, the command utility shall provide information concerning how a command name is interpreted by the shell.
The command utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
-p        Perform the command search using a default value for PATH that is guaranteed to find all of the standard utilities.
-v        Write a string to standard output that indicates the pathname or command that will be used by the shell, in the current shell execution environment (see Section 2.12, Shell Execution Environment), to invoke command_name, but do not invoke command_name.
*  Utilities, regular built-in utilities, command_names including a <slash> character, and any implementation- defined functions that are found using the PATH variable (as described in Section 2.9.1.1, Command Search and Execution), shall be written as absolute pathnames.
*  Shell functions, special built-in utilities, regular built- in utilities not associated with a PATH search, and shell reserved words shall be written as just their names.
*  An alias shall be written as a command line that represents its alias definition.
*  Otherwise, no output shall be written and the exit status shall reflect that the name was not found.
-V        Write a string to standard output that indicates how the name given in the command_name operand will be interpreted by the shell, in the current shell execution environment (see Section 2.12, Shell Execution Environment), but do not invoke command_name.  Although the format of this string is unspecified, it shall indicate in which of the following categories command_name falls and shall include the information stated:
*  Utilities, regular built-in utilities, and any implementation-defined functions that are found using the PATH variable (as described in Section 2.9.1.1, Command Search and Execution), shall be identified as such and include the absolute pathname in the string.
*  Other shell functions shall be identified as functions.
*  Aliases shall be identified as aliases and their definitions included in the string.
*  Special built-in utilities shall be identified as special built-in utilities.
*  Regular built-in utilities not associated with a PATH search shall be identified as regular built-in utilities. (The term ``regular'' need not be used.)
*  Shell reserved words shall be identified as reserved words.
argument  One of the strings treated as an argument to command_name.
command_name The name of a utility or a special built-in utility.
The following environment variables shall affect the execution of command:
PATH      Determine the search path used during the command search described in Section 2.9.1.1, Command Search and Execution, except as described under the -p option.
When the -v option is specified, standard output shall be formatted as:
"%s\n", <pathname or command>
When the -V option is specified, standard output shall be formatted as:
"%s\n", <unspecified>
When the -v or -V options are specified, the following exit values shall be returned:
>0    The command_name could not be found or an error occurred.
Otherwise, the following exit values shall be returned:
126   The utility specified by command_name was found but could not be invoked.
127   An error occurred in the command utility or the utility specified by command_name could not be found.
Otherwise, the exit status of command shall be that of the simple command specified by the arguments to command.
The order for command search allows functions to override regular built- ins and path searches. This utility is necessary to allow functions that have the same name as a utility to call the utility (instead of a recursive call to the function).
The system default path is available using getconf; however, since getconf may need to have the PATH set up before it can be called itself, the following can be used:
command -p getconf PATH
There are some advantages to suppressing the special characteristics of special built-ins on occasion. For example:
command exec > unwritable-file
does not cause a non-interactive script to abort, so that the output status can be checked by the script.
The command, env, nohup, time, and xargs utilities have been specified to use exit code 127 if an error occurs so that applications can distinguish ``failure to find a utility'' from ``invoked utility exited with an error indication''. The value 127 was chosen because it is not commonly used for other meanings; most utilities use small values for ``normal error conditions'' and the values above 128 can be confused with termination due to receipt of a signal. The value 126 was chosen in a similar manner to indicate that the utility could be found, but not invoked. Some scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction between exit codes 126 and 127 is based on KornShell practice that uses 127 when all attempts to exec the utility fail with [ENOENT], and uses 126 when any attempt to exec the utility fails for any other reason.
Since the -v and -V options of command produce output in relation to the current shell execution environment, command is generally provided as a shell regular built-in. If it is called in a subshell or separate utility execution environment, such as one of the following:
(PATH=foo command -v) nohup command -v
it does not necessarily produce correct results. For example, when called with nohup or an exec function, in a separate utility execution environment, most implementations are not able to identify aliases, functions, or special built-ins.
Two types of regular built-ins could be encountered on a system and these are described separately by command.  The description of command search in Section 2.9.1.1, Command Search and Execution allows for a standard utility to be implemented as a regular built-in as long as it is found in the appropriate place in a PATH search. So, for example, command -v true might yield /bin/true or some similar pathname. Other implementation- defined utilities that are not defined by this volume of POSIX.1‐2017 might exist only as built-ins and have no pathname associated with them. These produce output identified as (regular) built-ins. Applications encountering these are not able to count on execing them, using them with nohup, overriding them with a different PATH, and so on.
1. Make a version of cd that always prints out the new working directory exactly once:
cd() { command cd "$@" >/dev/null pwd }
2. Start off a ``secure shell script'' in which the script avoids being spoofed by its parent:
IFS=' ' #    The preceding value should be <space><tab><newline>. #    Set IFS to its default value.
\unalias -a #    Unset all possible aliases. #    Note that unalias is escaped to prevent an alias #    being used for unalias.
unset -f command #    Ensure command is not a user function.
PATH="$(command -p getconf PATH):$PATH" #    Put on a reliable PATH prefix.
#    ...
At this point, given correct permissions on the directories called by PATH, the script has the ability to ensure that any utility it calls is the intended one. It is being very cautious because it assumes that implementation extensions may be present that would allow user functions to exist when it is invoked; this capability is not specified by this volume of POSIX.1‐2017, but it is not prohibited as an extension. For example, the ENV variable precedes the invocation of the script with a user start-up script. Such a script could define functions to spoof the application.
Since command is a regular built-in utility it is always found prior to the PATH search.
There is nothing in the description of command that implies the command line is parsed any differently from that of any other simple command. For example:
command a | b ; c
is not parsed in any special way that causes '|' or ';' to be treated other than a pipe operator or <semicolon> or that prevents function lookup on b or c.
The command utility is somewhat similar to the Eighth Edition shell builtin command, but since command also goes to the file system to search for utilities, the name builtin would not be intuitive.
The command utility is most likely to be provided as a regular built-in. It is not listed as a special built-in for the following reasons:
*  The removal of exportable functions made the special precedence of a special built-in unnecessary.
*  A special built-in has special properties (see Section 2.14, Special Built-In Utilities) that were inappropriate for invoking other utilities. For example, two commands such as:
date > unwritable-file
command date > unwritable-file
would have entirely different results; in a non-interactive script, the former would continue to execute the next command, the latter would abort. Introducing this semantic difference along with suppressing functions was seen to be non-intuitive.
The -p option is present because it is useful to be able to ensure a safe path search that finds all the standard utilities. This search might not be identical to the one that occurs through one of the exec functions (as defined in the System Interfaces volume of POSIX.1‐2017) when PATH is unset. At the very least, this feature is required to allow the script to access the correct version of getconf so that the value of the default path can be accurately retrieved.
The command -v and -V options were added to satisfy requirements from users that are currently accomplished by three different historical utilities: type in the System V shell, whence in the KornShell, and which in the C shell. Since there is no historical agreement on how and what to accomplish here, the POSIX command utility was enhanced and the historical utilities were left unmodified.  The C shell which merely conducts a path search. The KornShell whence is more elaborate—in addition to the categories required by POSIX, it also reports on tracked aliases, exported aliases, and undefined functions.
The output format of -V was left mostly unspecified because human users are its only audience.  Applications should not be written to care about this information; they can use the output of -v to differentiate between various types of commands, but the additional information that may be emitted by the more verbose -V is not needed and should not be arbitrarily constrained in its verbosity or localization for application parsing reasons.
Section 2.9.1.1, Command Search and Execution, Section 2.12, Shell Execution Environment, Section 2.14, Special Built-In Utilities, sh, type
The System Interfaces volume of POSIX.1‐2017, exec
virt-sparsify(1)             Virtualization Support             virt-sparsify(1)
virt-sparsify - Make a virtual machine disk sparse
virt-sparsify [--options] indisk outdisk
virt-sparsify [--options] --in-place disk
Using "virt-sparsify" on live virtual machines, or concurrently with other disk editing tools, can be dangerous, potentially causing disk corruption.  The virtual machine must be shut down before you use this command, and disk images must not be edited concurrently.
Virt-sparsify is a tool which can make a virtual machine disk (or any disk image) sparse a.k.a. thin-provisioned.  This means that free space within the disk image can be converted back to free space on the host.
Virt-sparsify can locate and sparsify free space in most filesystems (eg. ext2/3/4, btrfs, NTFS, etc.), and also in LVM physical volumes.
Virt-sparsify can also convert between some disk formats, for example converting a raw disk image to a thin-provisioned qcow2 image.
Virt-sparsify can operate on any disk image, not just ones from virtual machines.  However if a virtual machine has multiple disks and uses volume management, then virt-sparsify will work but not be very effective (http://bugzilla.redhat.com/887826).
IMPORTANT NOTE ABOUT SPARSE OUTPUT IMAGES If the input is raw, then the default output is raw sparse.  You must check the output size using a tool that understands sparseness such as "du -sh".  It can make a huge difference:
$ ls -lh test1.img -rw-rw-r--. 1 rjones rjones 100M Aug  8 08:08 test1.img $ du -sh test1.img 3.6M   test1.img
(Compare the apparent size 100M vs the actual size 3.6M)
IMPORTANT LIMITATIONS •   The virtual machine must be shut down before using this tool.
•   Virt-sparsify may require up to 2x the virtual size of the source disk image (1 temporary copy + 1 destination image).  This is in the worst case and usually much less space is required.
If you are using the --in-place option, then large amounts of temporary space are not required.
•   Virt-sparsify cannot resize disk images.  To do that, use virt-resize(1).
•   Virt-sparsify cannot handle encrypted disks.  Libguestfs supports encrypted disks, but encrypted disks themselves cannot be sparsified.
•   Virt-sparsify cannot yet sparsify the space between partitions.  Note that this space is often used for critical items like bootloaders so it's not really unused.
•   In copy mode, qcow2 internal snapshots are not copied over to the destination image.
You may also want to read the manual pages for the associated tools virt-filesystems(1) and virt-df(1) before starting.
virt-sparsify indisk outdisk
which copies "indisk" to "outdisk", making the output sparse.  "outdisk" is created, or overwritten if it already exists.  The format of the input disk is detected (eg. qcow2) and the same format is used for the output disk.
To convert between formats, use the --convert option:
virt-sparsify disk.raw --convert qcow2 disk.qcow2
Virt-sparsify tries to zero and sparsify free space on every filesystem it can find within the source disk image.  You can get it to ignore (don't zero free space on) certain filesystems by doing:
virt-sparsify --ignore /dev/sda1 indisk outdisk
See virt-filesystems(1) to get a list of filesystems within a disk image.
Since virt-sparsify ≥ 1.26, you can now sparsify a disk image in place by doing:
virt-sparsify --in-place disk.img
--help Display help.
--check-tmpdir ignore --check-tmpdir continue --check-tmpdir warn --check-tmpdir fail Check if "TMPDIR" or --tmp directory has enough space to complete the operation.  This is just an estimate.
If the check indicates a problem, then you can either:
•   ignore it,
•   print a warning and continue,
•   warn and wait for the user to press the Return key (this is the default), or:
•   fail and exit.
You cannot use this option and --in-place together.
--compress Compress the output file.  This only works if the output format is "qcow2".
--convert raw --convert qcow2 --convert [other formats] Use "output-format" as the format for the destination image.  If this is not specified, then the input format is used.
Supported and known-working output formats are: "raw", "qcow2", "vdi".
You can also use any format supported by the qemu-img(1) program, eg. "vmdk", but support for other formats is reliant on qemu.
Specifying the --convert option is usually a good idea, because then virt-sparsify doesn't need to try to guess the input format.
For fine-tuning the output format, see: --compress, -o.
--echo-keys When prompting for keys and passphrases, virt-sparsify normally turns echoing off so you cannot see what you are typing.  If you are not worried about Tempest attacks and there is no one else in the room you can specify this flag to see what you are typing.
--format raw --format qcow2 Specify the format of the input disk image.  If this flag is not given then it is auto-detected from the image itself.
If working with untrusted raw-format guest disk images, you should ensure the format is always specified.
--ignore filesystem --ignore volgroup Ignore the named filesystem.
When not using --in-place: Free space on the filesystem will not be zeroed, but existing blocks of zeroes will still be sparsified.
When using --in-place, the filesystem is ignored completely.
In the second form, this ignores the named volume group.  Use the volume group name without the /dev/ prefix, eg. --ignore vg_foo
You can give this option multiple times.
--in-place Do in-place sparsification instead of copying sparsification.  See "IN-PLACE SPARSIFICATION" below.
--machine-readable --machine-readable=format This option is used to make the output more machine friendly when being parsed by other programs.  See "MACHINE READABLE OUTPUT" below.
-o option[,option,...] Pass -o option(s) to the qemu-img(1) command to fine-tune the output format.  Options available depend on the output format (see --convert) and the installed version of the qemu-img program.
You should use -o at most once.  To pass multiple options, separate them with commas, eg:
virt-sparsify --convert qcow2 \ -o cluster_size=512,preallocation=metadata ...
-q --quiet This disables progress bars and other unnecessary output.
--tmp block_device --tmp dir In copying mode only, use the named device or directory as the location of the temporary overlay (see also "TMPDIR" below).
If the parameter given is a block device, then the block device is written to directly.  Note this erases the existing contents of the block device.
If the parameter is a directory, then this is the same as setting the "TMPDIR" environment variable.
--tmp prebuilt:file In copying mode only, the specialized option --tmp prebuilt:file (where "prebuilt:" is a literal string) causes virt-sparsify to use the qcow2 "file" as temporary space.
•   The file must be freshly formatted as qcow2, with indisk as the backing file.
•   If you rerun virt-sparsify, you must recreate the file before each run.
•   Virt-sparsify does not delete the file.
This option is used by oVirt which requires a specially formatted temporary file.
--zero partition --zero logvol Zero the contents of the named partition or logical volume in the guest.  All data on the device is lost, but sparsification is excellent!  You can give this option multiple times.
IN-PLACE SPARSIFICATION Since virt-sparsify ≥ 1.26, the tool is able to do in-place sparsification (instead of copying from an input disk to an output disk). This is more efficient.  It is not able to recover quite as much space as copying sparsification.
To use this mode, specify a disk image which will be modified in place:
Some options are not compatible with this mode: --convert, --compress and -o because they require wholesale disk format changes; --check-tmpdir because large amounts of temporary space are not required.
In-place sparsification works using discard (a.k.a trim or unmap) support.
The --machine-readable option can be used to make the output more machine friendly, which is useful when calling virt-sparsify from other programs, GUIs etc.
There are two ways to use this option.
Firstly use the option on its own to query the capabilities of the virt- sparsify binary.  Typical output looks like this:
$ virt-sparsify --machine-readable virt-sparsify ntfs btrfs
A list of features is printed, one per line, and the program exits with status 0.
Secondly use the option in conjunction with other options to make the regular program output more machine friendly.
At the moment this means:
1.  Progress bar messages can be parsed from stdout by looking for this regular expression:
^[0-9]+/[0-9]+$
2.  The calling program should treat messages sent to stdout (except for progress bar messages) as status messages.  They can be logged and/or displayed to the user.
3.  The calling program should treat messages sent to stderr as error messages.  In addition, virt-sparsify exits with a non-zero status code if there was a fatal error.
All versions of virt-sparsify have supported the --machine-readable option.
It is possible to specify a format string for controlling the output; see "ADVANCED MACHINE READABLE OUTPUT" in guestfs(3).
WINDOWS 8 Windows 8 "fast startup" can prevent virt-sparsify from working.  See "WINDOWS HIBERNATION AND WINDOWS 8 FAST STARTUP" in guestfs(3).
TMPDIR Location of the temporary directory used for the potentially large temporary overlay file.
In virt-sparsify ≥ 1.28, you can override this environment variable using the --tmp option.
You should ensure there is enough free space in the worst case for a full copy of the source disk (virtual size), or else set $TMPDIR to point to another directory that has enough space.
This defaults to /tmp.
Note that if $TMPDIR is a tmpfs (eg. if /tmp is on tmpfs, or if you use "TMPDIR=/dev/shm"), tmpfs defaults to a maximum size of half of physical RAM.  If virt-sparsify exceeds this, it will hang.  The solution is either to use a real disk, or to increase the maximum size of the tmpfs mountpoint, eg:
mount -o remount,size=10G /tmp
This program returns 0 if the operation completed without errors.  (This doesn't necessarily mean that space could be freed up.)
A non-zero exit code indicates an error.
If the exit code is 3 and the --in-place option was used, that indicates that discard support is not available in libguestfs, so copying mode must be used instead.
virt-df(1), virt-filesystems(1), virt-resize(1), virt-rescue(1), guestfs(3), guestfish(1), truncate(1), fallocate(1), qemu-img(1), http://libguestfs.org/.
cpufreq-set(1)                                                    cpufreq-set(1)
cpufreq-set - A small tool which allows to modify cpufreq settings.
cpufreq-set [options]
cpufreq-set allows you to modify cpufreq settings without having to type e.g. "/sys/devices/system/cpu/cpu0/cpufreq/scaling_set_speed" all the time.
-c --cpu <CPU> number of CPU where cpufreq settings shall be modified.
-d --min <FREQ> new minimum CPU frequency the governor may select.
-u --max <FREQ> new maximum CPU frequency the governor may select.
-g --governor <GOV> new cpufreq governor.
-f --freq <FREQ> specific frequency to be set. Requires userspace governor to be available and loaded.
-r --related modify all hardware-related CPUs at the same time
-h --help Prints out the help screen.
Omitting the -c or --cpu argument is equivalent to setting it to zero.
The -f FREQ, --freq FREQ parameter cannot be combined with any other parameter except the -c CPU, --cpu CPU parameter.
FREQuencies can be passed in Hz, kHz (default), MHz, GHz, or THz by postfixing the value with the wanted unit name, without any space (frequency in kHz =^ Hz * 0.001 =^ MHz * 1000 =^ GHz * 1000000).
On Linux kernels up to 2.6.29, the -r or --related parameter is ignored.
/sys/devices/system/cpu/cpu*/cpufreq/ /proc/cpufreq (deprecated) /proc/sys/cpu/ (deprecated)
Dominik Brodowski <linux@brodo.de> - author Mattia Dongili<malattia@gmail.com> - first autolibtoolization
cpufreq-info(1)
MIXXX(1)                     General Commands Manual                    MIXXX(1)
mixxx — A Digital Disc Jockey Interface
mixxx is free DJ software that gives you everything you need to perform live DJ mixes. Blend songs together with automatic BPM matching and remix on-the-fly with looping and hot cues.  Whether you're a pro DJ or just getting started, Mixxx has you covered.
mixxx works with ALSA, JACK, OSS and supports many popular DJ controllers.
This manual page documents briefly the mixxx       command line options. It does not describe all of the features of mixxx or how to use it; Instead, it has a documentation in pdf format; see below.
KEY FEATURES
•  Parallel or split scratchable waveform displays.
•  MP3, OGG, WAVE, FLAC, and optional AAC (M4A) playback.
•  WAVE, OGG, and optional MP3 recording.
•  Fast, database-powered library.
•  Crates and playlists for organizing your music.
•  Reads iTunes, Traktor, and Rhythmbox libraries.
•  Cross-platform - works on Windows, Mac OS X and Linux.
•  Shoutcast and Icecast broadcasting.
•  Support for many DJ MIDI & HID controllers out-of-the-box.
•  Advanced MIDI scripting engine for maximum flexibility.
•  Vinyl emulation with Serato,Traktor, and Mixvibes timecode support.
•  Bulk BPM and beat detection.
•  ReplayGain volume normalization.
•  Automatic crossfading with Auto DJ.
•  Skinnable interface with several skins bundled.
For a full list of features go to: (link to URL http://mixxx.org/features/) .
mixxx does not have AAC (M4A) playback support enabled by default due to licensing restrictions. To enable playback of unprotected AAC (M4A) files, you can build mixxx from source. See also: (link to URL http://www.mixxx.org/wiki/doku.php/compiling_on_linux#build_with_m4a_file_support)
Mixxx is designed to be as user-friendly as possible. As such, its command line options are only useful for development or debugging, as they make these tasks easier. mixxx accepts the following case-sensitive options on the command-line:
<FILE> Load the specified music file(s) at start-up. Each file you specify will be loaded into the next virtual deck. Supported file types: mp3, ogg, aiff, aif, wav, flac
--resourcePath           <PATH> Top-level directory where Mixxx should look for its resource files such as MIDI mappings, overriding the default installation location.
--pluginPath           <PATH> Top-level directory where Mixxx should look for sound source plugins in addition to default locations.
--settingsPath           <PATH> Top-level directory where Mixxx should look for settings.
--controllerDebug/--midiDebug Causes Mixxx to display/log all of the MIDI/HID controller data it receives and script functions it loads.
--developer Enables developer-mode. Includes extra log info, stats on performance, and a Developer tools menu.
--locale           <LOCALE> Use a custom locale for loading translations (e.g 'fr').
--f           --fullScreen Starts mixxx in full-screen mode.
-h           --help Display a help message and exit.
/usr/share/doc/mixxx/Mixxx-Manual.pdf
The manual in pdf format should have come with your copy of mixxx, however there is an online copy available: (link to URL http://mixxx.org/wiki/doku.php/manual) .
~/.mixxx/ The directory where mixxx stores its user data.
~/.mixxx/mixxx.cfg The mixxx configuration file.
~/.mixxx/mixxxdb.sqlite The mixxx library file.  Warning: Deleting your library will lose all of your metadata. This includes saved hotcues, loops, comments, ratings, and other library related metadata. Only delete your library if you are fine with losing these.
~/.mixxx/analysis The directory where mixxx stores any additional analysis data that can't fit into the library file. Currently only the waveforms are saved here. If you delete your library file you should also delete this folder as the waveforms around 1MB each and are unusable without the library that generated them.
~/.mixxx/controllers The directory where mixxx stores user controller mappings.  All mappings that are created with the MIDI learning wizard are saved here. If there are mappings for a controller in the default resource directory and this directory mixxx will use the one saved here.
/usr/share/mixxx The directory where mixxx stores its default resources like skins, MIDI/HID controller mappings, keyboard mappings, and translations.
/usr/share/doc/mixxx/Mixxx-Manual.pdf The mixxx manual in pdf format.
To report a bug or request a feature, go to the mixxx bug tracker: (link to URL http://bugs.launchpad.net/mixxx)
Since 2000, over 150 developers, artists and translators have helped create mixxx. The current mixxx development team is led by RJ Ryan rryan@mixxx.org.
This manual page was written by S.Brandt s.brandt@mixxx.org for the Debian       system (and may be used by others).  Permission is granted to copy, distribute and/or modify this document under the terms of the GNU       General Public License, Version 2 any later version published by the Free Software Foundation.
On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-2.
History April 12, 2013 Completely revised for mixxx 1.11 by Max Linke and S.Brandt s.brandt@mixxx.org
November 26, 2004 Initial version by Paul Brossier piem@altern.org.
GIT-DELETE-BRANCH(1)               Git Extras               GIT-DELETE-BRANCH(1)
git-delete-branch - Delete branches
git-delete-branch <branchname>
Deletes local and remote branch named <branchname>. Note that local deletion fails if the branch is checked out.
The name of the branch to delete. If multiple branches are provided, then they will all be deleted.
$ git delete-branch integration $ git delete-branch integration bug/1234
CAKE(1)                      General Commands Manual                     CAKE(1)
cake - CakePHP application shell.
cake <shell>
The cake utility encapsulates a number of operations that can be performed on CakePHP applications, including generating controllers, views and models, as well as managing access control lists (ACLs), viewing API documentation and application-specific console tasks.
The available commands (or `shells') can be seen by running cake without any arguments.
cake was written by Larry E. Masters <phpnut@gmail.com>.