neulab/tldr huggingface dataset:
GENERATING C++ SCANNERS flex provides two different ways to generate scanners for use with C++. The first way is to simply compile a scanner generated by flex using a C++ compiler instead of a C compiler.  You should not encounter any compilations errors (please report any you find to the email address given in the Author section below).  You can then use C++ code in your rule actions instead of C code.  Note that the default input source for your scanner remains yyin, and default echoing is still done to yyout. Both of these remain FILE * variables and not C++ streams.
You can also use flex to generate a C++ scanner class, using the -+ option (or, equivalently, %option c++), which is automatically specified if the name of the flex executable ends in a '+', such as flex++.  When using this option, flex defaults to generating the scanner to the file lex.yy.cc instead of lex.yy.c.  The generated scanner includes the header file FlexLexer.h, which defines the interface to two C++ classes.
The first class, FlexLexer, provides an abstract base class defining the general scanner class interface.  It provides the following member functions:
const char* YYText() returns the text of the most recently matched token, the equivalent of yytext.
int YYLeng() returns the length of the most recently matched token, the equivalent of yyleng.
int lineno() const returns the current input line number (see %option yylineno), or 1 if %option yylineno was not used.
void set_debug( int flag ) sets the debugging flag for the scanner, equivalent to assigning to yy_flex_debug (see the Options section above).  Note that you must build the scanner using %option debug to include debugging information in it.
int debug() const returns the current setting of the debugging flag.
Also provided are member functions equivalent to yy_switch_to_buffer(), yy_create_buffer() (though the first argument is an istream* object pointer and not a FILE*), yy_flush_buffer(), yy_delete_buffer(), and yyrestart() (again, the first argument is a istream* object pointer).
The second class defined in FlexLexer.h is yyFlexLexer, which is derived from FlexLexer.  It defines the following additional member functions:
yyFlexLexer( istream* arg_yyin = 0, ostream* arg_yyout = 0 ) constructs a yyFlexLexer object using the given streams for input and output.  If not specified, the streams default to cin and cout, respectively.
virtual int yylex() performs the same role is yylex() does for ordinary flex scanners: it scans the input stream, consuming tokens, until a rule's action returns a value.  If you derive a subclass S from yyFlexLexer and want to access the member functions and variables of S inside yylex(), then you need to use %option yyclass="S" to inform flex that you will be using that subclass instead of yyFlexLexer.  In this case, rather than generating yyFlexLexer::yylex(), flex generates S::yylex() (and also generates a dummy yyFlexLexer::yylex() that calls yyFlexLexer::LexerError() if called).
virtual void switch_streams(istream* new_in = 0, ostream* new_out = 0) reassigns yyin to new_in (if non-nil) and yyout to new_out (ditto), deleting the previous input buffer if yyin is reassigned.
int yylex( istream* new_in, ostream* new_out = 0 ) first switches the input streams via switch_streams( new_in, new_out ) and then returns the value of yylex().
In addition, yyFlexLexer defines the following protected virtual functions which you can redefine in derived classes to tailor the scanner:
virtual int LexerInput( char* buf, int max_size ) reads up to max_size characters into buf and returns the number of characters read.  To indicate end-of-input, return 0 characters. Note that "interactive" scanners (see the -B and -I flags) define the macro YY_INTERACTIVE.  If you redefine LexerInput() and need to take different actions depending on whether or not the scanner might be scanning an interactive input source, you can test for the presence of this name via #ifdef.
virtual void LexerOutput( const char* buf, int size ) writes out size characters from the buffer buf, which, while NUL- terminated, may also contain "internal" NUL's if the scanner's rules can match text with NUL's in them.
virtual void LexerError( const char* msg ) reports a fatal error message.  The default version of this function writes the message to the stream cerr and exits.
Note that a yyFlexLexer object contains its entire scanning state.  Thus you can use such objects to create reentrant scanners.  You can instantiate multiple instances of the same yyFlexLexer class, and you can also combine multiple C++ scanner classes together in the same program using the -P option discussed above.
Finally, note that the %array feature is not available to C++ scanner classes; you must use %pointer (the default).
Here is an example of a simple C++ scanner:
// An example of using the flex C++ scanner class.
%{ int mylineno = 0; %}
string  \"[^\n"]+\"
ws      [ \t]+
alpha   [A-Za-z] dig     [0-9] name    ({alpha}|{dig}|\$)({alpha}|{dig}|[_.\-/$])* num1    [-+]?{dig}+\.?([eE][-+]?{dig}+)? num2    [-+]?{dig}*\.{dig}+([eE][-+]?{dig}+)? number  {num1}|{num2}
{ws}    /* skip blanks and tabs */
"/*"    { int c;
while((c = yyinput()) != 0) { if(c == '\n') ++mylineno;
else if(c == '*') { if((c = yyinput()) == '/') break; else unput(c); } } }
{number}  cout << "number " << YYText() << '\n';
\n        mylineno++;
{name}    cout << "name " << YYText() << '\n';
{string}  cout << "string " << YYText() << '\n';
int main( int /* argc */, char** /* argv */ ) { FlexLexer* lexer = new yyFlexLexer; while(lexer->yylex() != 0) ; return 0; } If you want to create multiple (different) lexer classes, you use the -P flag (or the prefix= option) to rename each yyFlexLexer to some other xxFlexLexer.  You then can include <FlexLexer.h> in your other sources once per lexer class, first renaming yyFlexLexer as follows:
#undef yyFlexLexer #define yyFlexLexer xxFlexLexer #include <FlexLexer.h>
#undef yyFlexLexer #define yyFlexLexer zzFlexLexer #include <FlexLexer.h>
if, for example, you used %option prefix="xx" for one of your scanners and %option prefix="zz" for the other.
IMPORTANT: the present form of the scanning class is experimental and may change considerably between major releases.
flex is a rewrite of the AT&T Unix lex tool (the two implementations do not share any code, though), with some extensions and incompatibilities, both of which are of concern to those who wish to write scanners acceptable to either implementation.  Flex is fully compliant with the POSIX lex specification, except that when using %pointer (the default), a call to unput() destroys the contents of yytext, which is counter to the POSIX specification.
In this section we discuss all of the known areas of incompatibility between flex, AT&T lex, and the POSIX specification.
flex's -l option turns on maximum compatibility with the original AT&T lex implementation, at the cost of a major loss in the generated scanner's performance.  We note below which incompatibilities can be overcome using the -l option.
flex is fully compatible with lex with the following exceptions:
-      The undocumented lex scanner internal variable yylineno is not supported unless -l or %option yylineno is used.
yylineno should be maintained on a per-buffer basis, rather than a per-scanner (single global variable) basis.
yylineno is not part of the POSIX specification.
-      The input() routine is not redefinable, though it may be called to read characters following whatever has been matched by a rule.  If input() encounters an end-of-file the normal yywrap() processing is done.  A ``real'' end-of-file is returned by input() as EOF.
Input is instead controlled by defining the YY_INPUT macro.
The flex restriction that input() cannot be redefined is in accordance with the POSIX specification, which simply does not specify any way of controlling the scanner's input other than by making an initial assignment to yyin.
-      The unput() routine is not redefinable.  This restriction is in accordance with POSIX.
-      flex scanners are not as reentrant as lex scanners.  In particular, if you have an interactive scanner and an interrupt handler which long-jumps out of the scanner, and the scanner is subsequently called again, you may get the following message:
fatal flex scanner internal error--end of buffer missed
To reenter the scanner, first use
yyrestart( yyin );
Note that this call will throw away any buffered input; usually this isn't a problem with an interactive scanner.
Also note that flex C++ scanner classes are reentrant, so if using C++ is an option for you, you should use them instead.  See "Generating C++ Scanners" above for details.
-      output() is not supported.  Output from the ECHO macro is done to the file-pointer yyout (default stdout).
output() is not part of the POSIX specification.
-      lex does not support exclusive start conditions (%x), though they are in the POSIX specification.
-      When definitions are expanded, flex encloses them in parentheses. With lex, the following:
NAME    [A-Z][A-Z0-9]* %% foo{NAME}?      printf( "Found it\n" ); %%
will not match the string "foo" because when the macro is expanded the rule is equivalent to "foo[A-Z][A-Z0-9]*?"  and the precedence is such that the '?' is associated with "[A-Z0-9]*".  With flex, the rule will be expanded to "foo([A-Z][A-Z0-9]*)?" and so the string "foo" will match.
Note that if the definition begins with ^ or ends with $ then it is not expanded with parentheses, to allow these operators to appear in definitions without losing their special meanings.  But the 
, /, and <<EOF>> operators cannot be used in a flex definition.
Using -l results in the lex behavior of no parentheses around the definition.
The POSIX specification is that the definition be enclosed in parentheses.
-      Some implementations of lex allow a rule's action to begin on a separate line, if the rule's pattern has trailing whitespace:
%% foo|bar<space here> { foobar_action(); }
flex does not support this feature.
-      The lex %r (generate a Ratfor scanner) option is not supported. It is not part of the POSIX specification.
-      After a call to unput(), yytext is undefined until the next token is matched, unless the scanner was built using %array.  This is not the case with lex or the POSIX specification.  The -l option does away with this incompatibility.
-      The precedence of the {} (numeric range) operator is different. lex interprets "abc{1,3}" as "match one, two, or three occurrences of 'abc'", whereas flex interprets it as "match 'ab' followed by one, two, or three occurrences of 'c'".  The latter is in agreement with the POSIX specification.
-      The precedence of the ^ operator is different.  lex interprets "^foo|bar" as "match either 'foo' at the beginning of a line, or 'bar' anywhere", whereas flex interprets it as "match either 'foo' or 'bar' if they come at the beginning of a line".  The latter is in agreement with the POSIX specification.
-      The special table-size declarations such as %a supported by lex are not required by flex scanners; flex ignores them.
-      The name FLEX_SCANNER is #define'd so scanners may be written for use with either flex or lex.  Scanners also include YY_FLEX_MAJOR_VERSION and YY_FLEX_MINOR_VERSION indicating which version of flex generated the scanner (for example, for the 2.5 release, these defines would be 2 and 5 respectively).
The following flex features are not included in lex or the POSIX specification:
C++ scanners %option start condition scopes start condition stacks interactive/non-interactive scanners yy_scan_string() and friends yyterminate() yy_set_interactive() yy_set_bol() YY_AT_BOL() <<EOF>> <*> YY_DECL YY_START YY_USER_ACTION YY_USER_INIT #line directives %{}'s around actions multiple actions on a line
plus almost all of the flex flags.  The last feature in the list refers to the fact that with flex you can put multiple actions on the same line, separated with semi-colons, while with lex, the following
foo    handle_foo(); ++num_foos_seen;
is (rather surprisingly) truncated to
foo    handle_foo();
flex does not truncate the action.  Actions that are not enclosed in braces are simply terminated at the end of the line.
warning, rule cannot be matched indicates that the given rule cannot be matched because it follows other rules that will always match the same text as it.  For example, in the following "foo" cannot be matched because it comes after an identifier "catch-all" rule:
[a-z]+    got_identifier(); foo       got_foo();
Using REJECT in a scanner suppresses this warning.
warning, -s option given but default rule can be matched means that it is possible (perhaps only in a particular start condition) that the default rule (match any single character) is the only one that will match a particular input.  Since -s was given, presumably this is not intended.
reject_used_but_not_detected undefined or yymore_used_but_not_detected undefined - These errors can occur at compile time.  They indicate that the scanner uses REJECT or yymore() but that flex failed to notice the fact, meaning that flex scanned the first two sections looking for occurrences of these actions and failed to find any, but somehow you snuck some in (via a #include file, for example).  Use %option reject or %option yymore to indicate to flex that you really do use these features.
flex scanner jammed - a scanner compiled with -s has encountered an input string which wasn't matched by any of its rules.  This error can also occur due to internal problems.
token too large, exceeds YYLMAX - your scanner uses %array and one of its rules matched a string longer than the YYLMAX constant (8K bytes by default).  You can increase the value by #define'ing YYLMAX in the definitions section of your flex input.
scanner requires -8 flag to use the character 'x' - Your scanner specification includes recognizing the 8-bit character 'x' and you did not specify the -8 flag, and your scanner defaulted to 7-bit because you used the -Cf or -CF table compression options.  See the discussion of the -7 flag for details.
flex scanner push-back overflow - you used unput() to push back so much text that the scanner's buffer could not hold both the pushed-back text and the current token in yytext.  Ideally the scanner should dynamically resize the buffer in this case, but at present it does not.
input buffer overflow, can't enlarge buffer because scanner uses REJECT - the scanner was working on matching an extremely large token and needed to expand the input buffer.  This doesn't work with scanners that use REJECT.
fatal flex scanner internal error--end of buffer missed - This can occur in an scanner which is reentered after a long-jump has jumped out (or over) the scanner's activation frame.  Before reentering the scanner, use:
or, as noted above, switch to using the C++ scanner class.
too many start conditions in <> construct! - you listed more start conditions in a <> construct than exist (so you must have listed at least one of them twice).
-lfl   library with which scanners must be linked.
lex.yy.c generated scanner (called lexyy.c on some systems).
lex.yy.cc generated C++ scanner class, when using -+.
<FlexLexer.h> header file defining the C++ scanner base class, FlexLexer, and its derived class, yyFlexLexer.
flex.skl skeleton scanner.  This file is only used when building flex, not when flex executes.
lex.backup backing-up information for -b flag (called lex.bck on some systems).
DEFICIENCIES / BUGS Some trailing context patterns cannot be properly matched and generate warning messages ("dangerous trailing context").  These are patterns where the ending of the first part of the rule matches the beginning of the second part, such as "zx*/xy*", where the 'x*' matches the 'x' at the beginning of the trailing context.  (Note that the POSIX draft states that the text matched by such patterns is undefined.)
For some trailing context rules, parts which are actually fixed-length are not recognized as such, leading to the abovementioned performance loss.  In particular, parts using '|' or {n} (such as "foo{3}") are always considered variable-length.
Combining trailing context with the special '|' action can result in fixed trailing context being turned into the more expensive variable trailing context.  For example, in the following:
%% abc      | xyz/def
Use of unput() invalidates yytext and yyleng, unless the %array directive or the -l option has been used.
Pattern-matching of NUL's is substantially slower than matching other characters.
Dynamic resizing of the input buffer is slow, as it entails rescanning all the text matched so far by the current (generally huge) token.
Due to both buffering of input and read-ahead, you cannot intermix calls to <stdio.h> routines, such as, for example, getchar(), with flex rules and expect it to work.  Call input() instead.
The total table entries listed by the -v flag excludes the number of table entries needed to determine what rule has been matched.  The number of entries is equal to the number of DFA states if the scanner does not use REJECT, and somewhat greater than the number of states if it does.
REJECT cannot be used with the -f or -F options.
The flex internal algorithms need documentation.
lex(1), yacc(1), sed(1), awk(1).
John Levine, Tony Mason, and Doug Brown, Lex & Yacc, O'Reilly and Associates.  Be sure to get the 2nd edition.
M. E. Lesk and E. Schmidt, LEX - Lexical Analyzer Generator
Alfred Aho, Ravi Sethi and Jeffrey Ullman, Compilers: Principles, Techniques and Tools, Addison-Wesley (1986).  Describes the pattern- matching techniques used by flex (deterministic finite automata).
Vern Paxson, with the help of many ideas and much inspiration from Van Jacobson.  Original version by Jef Poskanzer.  The fast table representation is a partial implementation of a design done by Van Jacobson.  The implementation was done by Kevin Gong and Vern Paxson.
Thanks to the many flex beta-testers, feedbackers, and contributors, especially Francois Pinard, Casey Leedom, Robert Abramovitz, Stan Adermann, Terry Allen, David Barker-Plummer, John Basrai, Neal Becker, Nelson H.F. Beebe, benson@odi.com, Karl Berry, Peter A. Bigot, Simon Blanchard, Keith Bostic, Frederic Brehm, Ian Brockbank, Kin Cho, Nick Christopher, Brian Clapper, J.T. Conklin, Jason Coughlin, Bill Cox, Nick Cropper, Dave Curtis, Scott David Daniels, Chris G. Demetriou, Theo Deraadt, Mike Donahue, Chuck Doucette, Tom Epperly, Leo Eskin, Chris Faylor, Chris Flatters, Jon Forrest, Jeffrey Friedl, Joe Gayda, Kaveh R. Ghazi, Wolfgang Glunz, Eric Goldman, Christopher M. Gould, Ulrich Grepel, Peer Griebel, Jan Hajic, Charles Hemphill, NORO Hideo, Jarkko Hietaniemi, Scott Hofmann, Jeff Honig, Dana Hudes, Eric Hughes, John Interrante, Ceriel Jacobs, Michal Jaegermann, Sakari Jalovaara, Jeffrey R. Jones, Henry Juengst, Klaus Kaempf, Jonathan I. Kamens, Terrence O Kane, Amir Katz, ken@ken.hilco.com, Kevin B. Kenny, Steve Kirsch, Winfried Koenig, Marq Kole, Ronald Lamprecht, Greg Lee, Rohan Lenard, Craig Leres, John Levine, Steve Liddle, David Loffredo, Mike Long, Mohamed el Lozy, Brian Madsen, Malte, Joe Marshall, Bengt Martensson, Chris Metcalf, Luke Mewburn, Jim Meyering, R. Alexander Milowski, Erik Naggum, G.T. Nicol, Landon Noll, James Nordby, Marc Nozell, Richard Ohnemus, Karsten Pahnke, Sven Panne, Roland Pesch, Walter Pelissero, Gaumond Pierre, Esmond Pitt, Jef Poskanzer, Joe Rahmeh, Jarmo Raiha, Frederic Raimbault, Pat Rankin, Rick Richardson, Kevin Rodgers, Kai Uwe Rommel, Jim Roskind, Alberto Santini, Andreas Scherer, Darrell Schiebel, Raf Schietekat, Doug Schmidt, Philippe Schnoebelen, Andreas Schwab, Larry Schwimmer, Alex Siegel, Eckehard Stolz, Jan-Erik Strvmquist, Mike Stump, Paul Stuart, Dave Tallman, Ian Lance Taylor, Chris Thewalt, Richard M. Timoney, Jodi Tsai, Paul Tuinenga, Gary Weik, Frank Whaley, Gerhard Wilhelms, Kent Williams, Ken Yap, Ron Zellar, Nathan Zelle, David Zuhn, and those whose names have slipped my marginal mail-archiving skills but whose contributions are appreciated all the same.
Thanks to Keith Bostic, Jon Forrest, Noah Friedman, John Gilmore, Craig Leres, John Levine, Bob Mulcahy, G.T.  Nicol, Francois Pinard, Rich Salz, and Richard Stallman for help with various distribution headaches.
Thanks to Esmond Pitt and Earle Horton for 8-bit character support; to Benson Margulies and Fred Burke for C++ support; to Kent Williams and Tom Epperly for C++ class support; to Ove Ewerlid for support of NUL's; and to Eric Hughes for support of multiple buffers.
This work was primarily done when I was with the Real Time Systems Group at the Lawrence Berkeley Laboratory in Berkeley, CA.  Many thanks to all there for the support I received.
Send comments to vern@ee.lbl.gov.
stow(8)                User Contributed Perl Documentation               stow(8)
stow - manage farms of symbolic links
stow [ options ] package ...
This manual page describes GNU Stow 2.3.1.  This is not the definitive documentation for Stow; for that, see the accompanying info manual, e.g. by typing "info stow".
Stow is a symlink farm manager which takes distinct sets of software and/or data located in separate directories on the filesystem, and makes them all appear to be installed in a single directory tree.
Originally Stow was born to address the need to administer, upgrade, install, and remove files in independent software packages without confusing them with other files sharing the same file system space.  For instance, many years ago it used to be common to compile programs such as Perl and Emacs from source.  By using Stow, /usr/local/bin could contain symlinks to files within /usr/local/stow/emacs/bin, /usr/local/stow/perl/bin etc., and likewise recursively for any other subdirectories such as .../share, .../man, and so on.
While this is useful for keeping track of system-wide and per-user installations of software built from source, in more recent times software packages are often managed by more sophisticated package management software such as rpm, dpkg, and Nix / GNU Guix, or language- native package managers such as Ruby's gem, Python's pip, Javascript's npm, and so on.
However Stow is still used not only for software package management, but also for other purposes, such as facilitating a more controlled approach to management of configuration files in the user's home directory, especially when coupled with version control systems.
Stow was inspired by Carnegie Mellon's Depot program, but is substantially simpler and safer. Whereas Depot required database files to keep things in sync, Stow stores no extra state between runs, so there's no danger (as there was in Depot) of mangling directories when file hierarchies don't match the database. Also unlike Depot, Stow will never delete any files, directories, or links that appear in a Stow directory (e.g., /usr/local/stow/emacs), so it's always possible to rebuild the target tree (e.g., /usr/local).
Stow is implemented as a combination of a Perl script providing a CLI interface, and a backend Perl module which does most of the work.
A "package" is a related collection of files and directories that you wish to administer as a unit -- e.g., Perl or Emacs -- and that needs to be installed in a particular directory structure -- e.g., with bin, lib, and man subdirectories.
A "target directory" is the root of a tree in which one or more packages wish to appear to be installed. A common, but by no means the only such location is /usr/local.  The examples in this manual page will use /usr/local as the target directory.
A "stow directory" is the root of a tree containing separate packages in private subtrees. When Stow runs, it uses the current directory as the default stow directory. The examples in this manual page will use /usr/local/stow as the stow directory, so that individual packages will be, for example, /usr/local/stow/perl and /usr/local/stow/emacs.
An "installation image" is the layout of files and directories required by a package, relative to the target directory. Thus, the installation image for Perl includes: a bin directory containing perl and a2p (among others); an info directory containing Texinfo documentation; a lib/perl directory containing Perl libraries; and a man/man1 directory containing man pages.
A "package directory" is the root of a tree containing the installation image for a particular package. Each package directory must reside in a stow directory -- e.g., the package directory /usr/local/stow/perl must reside in the stow directory /usr/local/stow.  The "name" of a package is the name of its directory within the stow directory -- e.g., perl.
Thus, the Perl executable might reside in /usr/local/stow/perl/bin/perl, where /usr/local is the target directory, /usr/local/stow is the stow directory, /usr/local/stow/perl is the package directory, and bin/perl within is part of the installation image.
A "symlink" is a symbolic link. A symlink can be "relative" or "absolute". An absolute symlink names a full path; that is, one starting from /.  A relative symlink names a relative path; that is, one not starting from /.  The target of a relative symlink is computed starting from the symlink's own directory.  Stow only creates relative symlinks.
The stow directory is assumed to be the value of the "STOW_DIR" environment variable or if unset the current directory, and the target directory is assumed to be the parent of the current directory (so it is typical to execute stow from the directory /usr/local/stow).  Each package given on the command line is the name of a package in the stow directory (e.g., perl).  By default, they are installed into the target directory (but they can be deleted instead using "-D").
-n --no Do not perform any operations that modify the filesystem; merely show what would happen.
-d DIR --dir=DIR Set the stow directory to "DIR" instead of the current directory. This also has the effect of making the default target directory be the parent of "DIR".
-t DIR --target=DIR Set the target directory to "DIR" instead of the parent of the stow directory.
-v --verbose[=N] Send verbose output to standard error describing what Stow is doing. Verbosity levels are from 0 to 5; 0 is the default.  Using "-v" or "--verbose" increases the verbosity by one; using `--verbose=N' sets it to N.
-S --stow Stow the packages that follow this option into the target directory. This is the default action and so can be omitted if you are only stowing packages rather than performing a mixture of stow/delete/restow actions.
-D --delete Unstow the packages that follow this option from the target directory rather than installing them.
-R --restow Restow packages (first unstow, then stow again). This is useful for pruning obsolete symlinks from the target tree after updating the software in a package.
--adopt Warning!  This behaviour is specifically intended to alter the contents of your stow directory.  If you do not want that, this option is not for you.
When stowing, if a target is encountered which already exists but is a plain file (and hence not owned by any existing stow package), then normally Stow will register this as a conflict and refuse to proceed. This option changes that behaviour so that the file is moved to the same relative place within the package's installation image within the stow directory, and then stowing proceeds as before.  So effectively, the file becomes adopted by the stow package, without its contents changing.
--no-folding Disable folding of newly stowed directories when stowing, and refolding of newly foldable directories when unstowing.
--ignore=REGEX Ignore files ending in this Perl regex.
--defer=REGEX Don't stow files beginning with this Perl regex if the file is already stowed to another package.
--override=REGEX Force stowing files beginning with this Perl regex if the file is already stowed to another package.
--dotfiles Enable special handling for "dotfiles" (files or folders whose name begins with a period) in the package directory. If this option is enabled, Stow will add a preprocessing step for each file or folder whose name begins with "dot-", and replace the "dot-" prefix in the name by a period (.). This is useful when Stow is used to manage collections of dotfiles, to avoid having a package directory full of hidden files.
For example, suppose we have a package containing two files, stow/dot-bashrc and stow/dot-emacs.d/init.el. With this option, Stow will create symlinks from .bashrc to stow/dot-bashrc and from .emacs.d/init.el to stow/dot-emacs.d/init.el. Any other files, whose name does not begin with "dot-", will be processed as usual.
-V --version Show Stow version number, and exit.
-h --help Show Stow command syntax, and exit.
The default action of Stow is to install a package. This means creating symlinks in the target tree that point into the package tree.  Stow attempts to do this with as few symlinks as possible; in other words, if Stow can create a single symlink that points to an entire subtree within the package tree, it will choose to do that rather than create a directory in the target tree and populate it with symlinks.
For example, suppose that no packages have yet been installed in /usr/local; it's completely empty (except for the stow subdirectory, of course). Now suppose the Perl package is installed.  Recall that it includes the following directories in its installation image: bin; info; lib/perl; man/man1.  Rather than creating the directory /usr/local/bin and populating it with symlinks to ../stow/perl/bin/perl and ../stow/perl/bin/a2p (and so on), Stow will create a single symlink, /usr/local/bin, which points to stow/perl/bin.  In this way, it still works to refer to /usr/local/bin/perl and /usr/local/bin/a2p, and fewer symlinks have been created. This is called "tree folding", since an entire subtree is "folded" into a single symlink.
To complete this example, Stow will also create the symlink /usr/local/info pointing to stow/perl/info; the symlink /usr/local/lib pointing to stow/perl/lib; and the symlink /usr/local/man pointing to stow/perl/man.
Now suppose that instead of installing the Perl package into an empty target tree, the target tree is not empty to begin with. Instead, it contains several files and directories installed under a different system-administration philosophy. In particular, /usr/local/bin already exists and is a directory, as are /usr/local/lib and /usr/local/man/man1. In this case, Stow will descend into /usr/local/bin and create symlinks to ../stow/perl/bin/perl and ../stow/perl/bin/a2p (etc.), and it will descend into /usr/local/lib and create the tree-folding symlink perl pointing to ../stow/perl/lib/perl, and so on. As a rule, Stow only descends as far as necessary into the target tree when it can create a tree-folding symlink.
The time often comes when a tree-folding symlink has to be undone because another package uses one or more of the folded subdirectories in its installation image. This operation is called "splitting open" a folded tree. It involves removing the original symlink from the target tree, creating a true directory in its place, and then populating the new directory with symlinks to the newly-installed package and to the old package that used the old symlink. For example, suppose that after installing Perl into an empty /usr/local, we wish to install Emacs. Emacs's installation image includes a bin directory containing the emacs and etags executables, among others. Stow must make these files appear to be installed in /usr/local/bin, but presently /usr/local/bin is a symlink to stow/perl/bin.  Stow therefore takes the following steps: the symlink /usr/local/bin is deleted; the directory /usr/local/bin is created; links are made from /usr/local/bin to ../stow/emacs/bin/emacs and ../stow/emacs/bin/etags; and links are made from /usr/local/bin to ../stow/perl/bin/perl and ../stow/perl/bin/a2p.
When splitting open a folded tree, Stow makes sure that the symlink it is about to remove points inside a valid package in the current stow directory.
Stow will never delete anything that it doesn't own. Stow "owns" everything living in the target tree that points into a package in the stow directory. Anything Stow owns, it can recompute if lost. Note that by this definition, Stow doesn't "own" anything in the stow directory or in any of the packages.
If Stow needs to create a directory or a symlink in the target tree and it cannot because that name is already in use and is not owned by Stow, then a conflict has arisen. See the "Conflicts" section in the info manual.
When the "-D" option is given, the action of Stow is to delete a package from the target tree. Note that Stow will not delete anything it doesn't "own". Deleting a package does not mean removing it from the stow directory or discarding the package tree.
To delete a package, Stow recursively scans the target tree, skipping over the stow directory (since that is usually a subdirectory of the target tree) and any other stow directories it encounters (see "Multiple stow directories" in the info manual). Any symlink it finds that points into the package being deleted is removed. Any directory that contained only symlinks to the package being deleted is removed. Any directory that, after removing symlinks and empty subdirectories, contains only symlinks to a single other package, is considered to be a previously "folded" tree that was "split open."  Stow will re-fold the tree by removing the symlinks to the surviving package, removing the directory, then linking the directory back to the surviving package.
Stow searches for default command line options at .stowrc (current directory) and ~/.stowrc (home directory) in that order. If both locations are present, the files are effectively appended together.
The effect of options in the resource file is similar to simply prepending the options to the command line. For options that provide a single value, such as --target or --dir, the command line option will overwrite any options in the resource file. For options that can be given more than once, --ignore for example, command line options and resource options are appended together.
Environment variables and the tilde character (~) will be expanded for options that take a file path.
The options -D, -R, -S, and any packages listed in the resource file are ignored.
See the info manual for more information on how stow handles resource file.
The full documentation for stow is maintained as a Texinfo manual.  If the info and stow programs are properly installed at your site, the command
info stow
Please report bugs in Stow using the Debian bug tracking system.
Currently known bugs include:
•   The empty-directory problem.
If package foo includes an empty directory -- say, foo/bar -- then if no other package has a bar subdirectory, everything's fine.  If another stowed package quux, has a bar subdirectory, then when stowing, targetdir/bar will be "split open" and the contents of quux/bar will be individually stowed.  So far, so good. But when unstowing quux, targetdir/bar will be removed, even though foo/bar needs it to remain.  A workaround for this problem is to create a file in foo/bar as a placeholder. If you name that file .placeholder, it will be easy to find and remove such files when this bug is fixed.
•   When using multiple stow directories (see "Multiple stow directories" in the info manual), Stow fails to "split open" tree-folding symlinks (see "Installing packages" in the info manual) that point into a stow directory which is not the one in use by the current Stow command. Before failing, it should search the target of the link to see whether any element of the path contains a .stow file. If it finds one, it can "learn" about the cooperating stow directory to short- circuit the .stow search the next time it encounters a tree-folding symlink.
This man page was originally constructed by Charles Briscoe-Smith from parts of Stow's info manual, and then converted to POD format by Adam Spiers.  The info manual contains the following notice, which, as it says, applies to this manual page, too.  The text of the section entitled "GNU General Public License" can be found in the file /usr/share/common-licenses/GPL on any Debian GNU/Linux system.  If you don't have access to a Debian system, or the GPL is not there, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA.
Copyright (C) 1993, 1994, 1995, 1996 by Bob Glickstein <bobg+stow@zanshin.com>; 2000, 2001 by Guillaume Morin; 2007 by Kahlil Hodgson; 2011 by Adam Spiers; and others.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included with the modified manual, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.
USERADD(8)                 System Management Commands                 USERADD(8)
useradd - create a new user or update default new user information
useradd [options] LOGIN
useradd -D
useradd -D [options]
When invoked without the -D option, the useradd command creates a new user account using the values specified on the command line plus the default values from the system. Depending on command line options, the useradd command will update system files and may also create the new user's home directory and copy initial files.
By default, a group will also be created for the new user (see -g, -N, -U, and USERGROUPS_ENAB).
The options which apply to the useradd command are:
--badname Allow names that do not conform to standards.
-b, --base-dir BASE_DIR The default base directory for the system if -d HOME_DIR is not specified.  BASE_DIR is concatenated with the account name to define the home directory. If the -m option is not used, BASE_DIR must exist.
If this option is not specified, useradd will use the base directory specified by the HOME variable in /etc/default/useradd, or /home by default.
-c, --comment COMMENT Any text string. It is generally a short description of the login, and is currently used as the field for the user's full name.
-d, --home-dir HOME_DIR The new user will be created using HOME_DIR as the value for the user's login directory. The default is to append the LOGIN name to BASE_DIR and use that as the login directory name. The directory HOME_DIR does not have to exist but will not be created if it is missing.
-D, --defaults See below, the subsection "Changing the default values".
If not specified, useradd will use the default expiry date specified by the EXPIRE variable in /etc/default/useradd, or an empty string (no expiry) by default.
-f, --inactive INACTIVE The number of days after a password expires until the account is permanently disabled. A value of 0 disables the account as soon as the password has expired, and a value of -1 disables the feature.
If not specified, useradd will use the default inactivity period specified by the INACTIVE variable in /etc/default/useradd, or -1 by default.
-g, --gid GROUP The group name or number of the user's initial login group. The group name must exist. A group number must refer to an already existing group.
If not specified, the behavior of useradd will depend on the USERGROUPS_ENAB variable in /etc/login.defs. If this variable is set to yes (or -U/--user-group is specified on the command line), a group will be created for the user, with the same name as her loginname. If the variable is set to no (or -N/--no-user-group is specified on the command line), useradd will set the primary group of the new user to the value specified by the GROUP variable in /etc/default/useradd, or 100 by default.
-G, --groups GROUP1[,GROUP2,...[,GROUPN]]] A list of supplementary groups which the user is also a member of. Each group is separated from the next by a comma, with no intervening whitespace. The groups are subject to the same restrictions as the group given with the -g option. The default is for the user to belong only to the initial group.
-k, --skel SKEL_DIR The skeleton directory, which contains files and directories to be copied in the user's home directory, when the home directory is created by useradd.
This option is only valid if the -m (or --create-home) option is specified.
If this option is not set, the skeleton directory is defined by the SKEL variable in /etc/default/useradd or, by default, /etc/skel.
If possible, the ACLs and extended attributes are copied.
-K, --key KEY=VALUE Overrides /etc/login.defs defaults (UID_MIN, UID_MAX, UMASK, PASS_MAX_DAYS and others).
Example: -K PASS_MAX_DAYS=-1 can be used when creating system account to turn off password aging, even though system account has no password at all. Multiple -K options can be specified, e.g.: -K UID_MIN=100  -K UID_MAX=499
-l, --no-log-init Do not add the user to the lastlog and faillog databases.
By default, the user's entries in the lastlog and faillog databases are reset to avoid reusing the entry from a previously deleted user.
-m, --create-home Create the user's home directory if it does not exist. The files and directories contained in the skeleton directory (which can be defined with the -k option) will be copied to the home directory.
By default, if this option is not specified and CREATE_HOME is not enabled, no home directories are created.
-M, --no-create-home Do no create the user's home directory, even if the system wide setting from /etc/login.defs (CREATE_HOME) is set to yes.
-N, --no-user-group Do not create a group with the same name as the user, but add the user to the group specified by the -g option or by the GROUP variable in /etc/default/useradd.
The default behavior (if the -g, -N, and -U options are not specified) is defined by the USERGROUPS_ENAB variable in /etc/login.defs.
-o, --non-unique Allow the creation of a user account with a duplicate (non-unique) UID.
This option is only valid in combination with the -u option.
-p, --password PASSWORD The encrypted password, as returned by crypt(3). The default is to disable the password.
-r, --system Create a system account.
System users will be created with no aging information in /etc/shadow, and their numeric identifiers are chosen in the SYS_UID_MIN-SYS_UID_MAX range, defined in /etc/login.defs, instead of UID_MIN-UID_MAX (and their GID counterparts for the creation of groups).
Note that useradd will not create a home directory for such a user, regardless of the default setting in /etc/login.defs (CREATE_HOME). You have to specify the -m options if you want a home directory for a system account to be created.
-s, --shell SHELL The name of the user's login shell. The default is to leave this field blank, which causes the system to select the default login shell specified by the SHELL variable in /etc/default/useradd, or an empty string by default.
-u, --uid UID The numerical value of the user's ID. This value must be unique, unless the -o option is used. The value must be non-negative. The default is to use the smallest ID value greater than or equal to UID_MIN and greater than every other user.
See also the -r option and the UID_MAX description.
-U, --user-group Create a group with the same name as the user, and add the user to this group.
-Z, --selinux-user SEUSER The SELinux user for the user's login. The default is to leave this field blank, which causes the system to select the default SELinux user.
Changing the default values When invoked with only the -D option, useradd will display the current default values. When invoked with -D plus other options, useradd will update the default values for the specified options. Valid default-changing options are:
-b, --base-dir BASE_DIR The path prefix for a new user's home directory. The user's name will be affixed to the end of BASE_DIR to form the new user's home directory name, if the -d option is not used when creating a new account.
This option sets the HOME variable in /etc/default/useradd.
-e, --expiredate EXPIRE_DATE The date on which the user account is disabled.
This option sets the EXPIRE variable in /etc/default/useradd.
-f, --inactive INACTIVE The number of days after a password has expired before the account will be disabled.
This option sets the INACTIVE variable in /etc/default/useradd.
-g, --gid GROUP The group name or ID for a new user's initial group (when the -N/--no-user-group is used or when the USERGROUPS_ENAB variable is set to no in /etc/login.defs). The named group must exist, and a numerical group ID must have an existing entry.
This option sets the GROUP variable in /etc/default/useradd.
-s, --shell SHELL The name of a new user's login shell.
This option sets the SHELL variable in /etc/default/useradd.
The system administrator is responsible for placing the default user files in the /etc/skel/ directory (or any other skeleton directory specified in /etc/default/useradd or on the command line).
You may not add a user to a NIS or LDAP group. This must be performed on the corresponding server.
Similarly, if the username already exists in an external user database such as NIS or LDAP, useradd will deny the user account creation request.
Usernames must start with a lower case letter or an underscore, followed by lower case letters, digits, underscores, or dashes. They can end with a dollar sign. In regular expression terms: [a-z_][a-z0-9_-]*[$]?
Usernames may only be up to 32 characters long.
CREATE_HOME (boolean) Indicate if a home directory should be created by default for new users.
This setting does not apply to system users, and can be overridden on the command line.
GID_MAX (number), GID_MIN (number) Range of group IDs used for the creation of regular groups by useradd, groupadd, or newusers.
The default value for GID_MIN (resp.  GID_MAX) is 1000 (resp. 60000).
HOME_MODE (number) The mode for new home directories. If not specified, the UMASK is used to create the mode.
useradd and newusers use this to set the mode of the home directory they create.
PASS_MAX_DAYS (number) The maximum number of days a password may be used. If the password is older than this, a password change will be forced. If not specified, -1 will be assumed (which disables the restriction).
PASS_MIN_DAYS (number) The minimum number of days allowed between password changes. Any password changes attempted sooner than this will be rejected. If not specified, -1 will be assumed (which disables the restriction).
PASS_WARN_AGE (number) The number of days warning given before a password expires. A zero means warning is given only upon the day of expiration, a negative value means no warning is given. If not specified, no warning will be provided.
SYS_GID_MAX (number), SYS_GID_MIN (number) Range of group IDs used for the creation of system groups by useradd, groupadd, or newusers.
The default value for SYS_GID_MIN (resp.  SYS_GID_MAX) is 101 (resp. GID_MIN-1).
SYS_UID_MAX (number), SYS_UID_MIN (number) Range of user IDs used for the creation of system users by useradd or newusers.
The default value for SYS_UID_MIN (resp.  SYS_UID_MAX) is 101 (resp. UID_MIN-1).
UID_MAX (number), UID_MIN (number) Range of user IDs used for the creation of regular users by useradd or newusers.
The default value for UID_MIN (resp.  UID_MAX) is 1000 (resp. 60000).
UMASK (number) The file mode creation mask is initialized to this value. If not specified, the mask will be initialized to 022.
useradd and newusers use this mask to set the mode of the home directory they create if HOME_MODE is not set.
It is also used by login to define users' initial umask. Note that this mask can be overridden by the user's GECOS line (if QUOTAS_ENAB is set) or by the specification of a limit with the K identifier in limits(5).
/etc/default/useradd Default values for account creation.
/etc/skel/ Directory containing default files.
The useradd command exits with the following values:
3 invalid argument to option
4 UID already in use (and no -o)
9 username already in use
12 can't create home directory
14 can't update SELinux user mapping
chfn(1), chsh(1), passwd(1), crypt(3), groupadd(8), groupdel(8), groupmod(8), login.defs(5), newusers(8), subgid(5), subuid(5), userdel(8), usermod(8).
HDPARM(8)                    System Manager's Manual                   HDPARM(8)
hdparm - get/set SATA/IDE device parameters
hdparm [options] [device ...]