neulab/tldr huggingface dataset:
If the O_DSYNC and O_RSYNC bits have been set, read I/O operations on the file descriptor shall complete as defined by synchronized I/O data integrity completion. If the O_SYNC and O_RSYNC bits have been set, read I/O operations on the file descriptor shall complete as defined by synchronized I/O file integrity completion.
If fildes refers to a shared memory object, the result of the read() function is unspecified.
If fildes refers to a typed memory object, the result of the read() function is unspecified.
A read() from a STREAMS file can read data in three different modes: byte-stream mode, message-nondiscard mode, and message-discard mode. The default shall be byte-stream mode.  This can be changed using the I_SRDOPT ioctl() request, and can be tested with I_GRDOPT ioctl().  In byte-stream mode, read() shall retrieve data from the STREAM until as many bytes as were requested are transferred, or until there is no more data to be retrieved.  Byte-stream mode ignores message boundaries.
In STREAMS message-nondiscard mode, read() shall retrieve data until as many bytes as were requested are transferred, or until a message boundary is reached. If read() does not retrieve all the data in a message, the remaining data shall be left on the STREAM, and can be retrieved by the next read() call. Message-discard mode also retrieves data until as many bytes as were requested are transferred, or a message boundary is reached.  However, unread data remaining in a message after the read() returns shall be discarded, and shall not be available for a subsequent read(), getmsg(), or getpmsg() call.
How read() handles zero-byte STREAMS messages is determined by the current read mode setting. In byte-stream mode, read() shall accept data until it has read nbyte bytes, or until there is no more data to read, or until a zero-byte message block is encountered. The read() function shall then return the number of bytes read, and place the zero-byte message back on the STREAM to be retrieved by the next read(), getmsg(), or getpmsg().  In message-nondiscard mode or message-discard mode, a zero- byte message shall return 0 and the message shall be removed from the STREAM. When a zero-byte message is read as the first message on a STREAM, the message shall be removed from the STREAM and 0 shall be returned, regardless of the read mode.
A read() from a STREAMS file shall return the data in the message at the front of the STREAM head read queue, regardless of the priority band of the message.
By default, STREAMs are in control-normal mode, in which a read() from a STREAMS file can only process messages that contain a data part but do not contain a control part. The read() shall fail if a message containing a control part is encountered at the STREAM head. This default action can be changed by placing the STREAM in either control-data mode or control- discard mode with the I_SRDOPT ioctl() command. In control-data mode, read() shall convert any control part to data and pass it to the application before passing any data part originally present in the same message.  In control-discard mode, read() shall discard message control parts but return to the process any data part in the message.
In addition, read() shall fail if the STREAM head had processed an asynchronous error before the call. In this case, the value of errno shall not reflect the result of read(), but reflect the prior error. If a hangup occurs on the STREAM being read, read() shall continue to operate normally until the STREAM head read queue is empty. Thereafter, it shall return 0.
The pread() function shall be equivalent to read(), except that it shall read from a given position in the file without changing the file offset. The first three arguments to pread() are the same as read() with the addition of a fourth argument offset for the desired position inside the file. An attempt to perform a pread() on a file that is incapable of seeking shall result in an error.
Upon successful completion, these functions shall return a non-negative integer indicating the number of bytes actually read. Otherwise, the functions shall return -1 and set errno to indicate the error.
These functions shall fail if:
EAGAIN The file is neither a pipe, nor a FIFO, nor a socket, the O_NONBLOCK flag is set for the file descriptor, and the thread would be delayed in the read operation.
EBADF  The fildes argument is not a valid file descriptor open for reading.
EBADMSG The file is a STREAM file that is set to control-normal mode and the message waiting to be read includes a control part.
EINTR  The read operation was terminated due to the receipt of a signal, and no data was transferred.
EINVAL The STREAM or multiplexer referenced by fildes is linked (directly or indirectly) downstream from a multiplexer.
EIO    The process is a member of a background process group attempting to read from its controlling terminal, and either the calling thread is blocking SIGTTIN or the process is ignoring SIGTTIN or the process group of the process is orphaned. This error may also be generated for implementation-defined reasons.
EISDIR The fildes argument refers to a directory and the implementation does not allow the directory to be read using read() or pread(). The readdir() function should be used instead.
EOVERFLOW The file is a regular file, nbyte is greater than 0, the starting position is before the end-of-file, and the starting position is greater than or equal to the offset maximum established in the open file description associated with fildes.
The pread() function shall fail if:
EINVAL The file is a regular file or block special file, and the offset argument is negative. The file offset shall remain unchanged.
ESPIPE The file is incapable of seeking.
The read() function shall fail if:
EAGAIN The file is a pipe or FIFO, the O_NONBLOCK flag is set for the file descriptor, and the thread would be delayed in the read operation.
EAGAIN or EWOULDBLOCK The file is a socket, the O_NONBLOCK flag is set for the file descriptor, and the thread would be delayed in the read operation.
ECONNRESET A read was attempted on a socket and the connection was forcibly closed by its peer.
ENOTCONN A read was attempted on a socket that is not connected.
ETIMEDOUT A read was attempted on a socket and a transmission timeout occurred.
These functions may fail if:
EIO    A physical I/O error has occurred.
ENOBUFS Insufficient resources were available in the system to perform the operation.
ENOMEM Insufficient memory was available to fulfill the request.
ENXIO  A request was made of a nonexistent device, or the request was outside the capabilities of the device.
Reading Data into a Buffer The following example reads data from the file associated with the file descriptor fd into the buffer pointed to by buf.
#include <sys/types.h> #include <unistd.h> ... char buf[20]; size_t nbytes; ssize_t bytes_read; int fd; ... nbytes = sizeof(buf); bytes_read = read(fd, buf, nbytes); ...
This volume of POSIX.1‐2017 does not specify the value of the file offset after an error is returned; there are too many cases. For programming errors, such as [EBADF], the concept is meaningless since no file is involved. For errors that are detected immediately, such as [EAGAIN], clearly the offset should not change. After an interrupt or hardware error, however, an updated value would be very useful and is the behavior of many implementations.
Note that a read() of zero bytes does not modify the last data access timestamp. A read() that requests more than zero bytes, but returns zero, is required to modify the last data access timestamp.
Implementations are allowed, but not required, to perform error checking for read() requests of zero bytes.
Input and Output The use of I/O with large byte counts has always presented problems. Ideas such as lread() and lwrite() (using and returning longs) were considered at one time. The current solution is to use abstract types on the ISO C standard function to read() and write().  The abstract types can be declared so that existing functions work, but can also be declared so that larger types can be represented in future implementations. It is presumed that whatever constraints limit the maximum range of size_t also limit portable I/O requests to the same range. This volume of POSIX.1‐2017 also limits the range further by requiring that the byte count be limited so that a signed return value remains meaningful. Since the return type is also a (signed) abstract type, the byte count can be defined by the implementation to be larger than an int can hold.
The standard developers considered adding atomicity requirements to a pipe or FIFO, but recognized that due to the nature of pipes and FIFOs there could be no guarantee of atomicity of reads of {PIPE_BUF} or any other size that would be an aid to applications portability.
This volume of POSIX.1‐2017 requires that no action be taken for read() or write() when nbyte is zero. This is not intended to take precedence over detection of errors (such as invalid buffer pointers or file descriptors). This is consistent with the rest of this volume of POSIX.1‐2017, but the phrasing here could be misread to require detection of the zero case before any other errors.  A value of zero is to be considered a correct value, for which the semantics are a no-op.
I/O is intended to be atomic to ordinary files and pipes and FIFOs. Atomic means that all the bytes from a single operation that started out together end up together, without interleaving from other I/O operations. It is a known attribute of terminals that this is not honored, and terminals are explicitly (and implicitly permanently) excepted, making the behavior unspecified. The behavior for other device types is also left unspecified, but the wording is intended to imply that future standards might choose to specify atomicity (or not).
There were recommendations to add format parameters to read() and write() in order to handle networked transfers among heterogeneous file system and base hardware types. Such a facility may be required for support by the OSI presentation of layer services. However, it was determined that this should correspond with similar C-language facilities, and that is beyond the scope of this volume of POSIX.1‐2017. The concept was suggested to the developers of the ISO C standard for their consideration as a possible area for future work.
In 4.3 BSD, a read() or write() that is interrupted by a signal before transferring any data does not by default return an [EINTR] error, but is restarted. In 4.2 BSD, 4.3 BSD, and the Eighth Edition, there is an additional function, select(), whose purpose is to pause until specified activity (data to read, space to write, and so on) is detected on specified file descriptors. It is common in applications written for those systems for select() to be used before read() in situations (such as keyboard input) where interruption of I/O due to a signal is desired.
The issue of which files or file types are interruptible is considered an implementation design issue. This is often affected primarily by hardware and reliability issues.
There are no references to actions taken following an ``unrecoverable error''. It is considered beyond the scope of this volume of POSIX.1‐2017 to describe what happens in the case of hardware errors.
Earlier versions of this standard allowed two very different behaviors with regard to the handling of interrupts. In order to minimize the resulting confusion, it was decided that POSIX.1‐2008 should support only one of these behaviors. Historical practice on AT&T-derived systems was to have read() and write() return -1 and set errno to [EINTR] when interrupted after some, but not all, of the data requested had been transferred. However, the US Department of Commerce FIPS 151‐1 and FIPS 151‐2 require the historical BSD behavior, in which read() and write() return the number of bytes actually transferred before the interrupt.  If -1 is returned when any data is transferred, it is difficult to recover from the error on a seekable device and impossible on a non-seekable device. Most new implementations support this behavior.  The behavior required by POSIX.1‐2008 is to return the number of bytes transferred.
POSIX.1‐2008 does not specify when an implementation that buffers read()s actually moves the data into the user-supplied buffer, so an implementation may choose to do this at the latest possible moment. Therefore, an interrupt arriving earlier may not cause read() to return a partial byte count, but rather to return -1 and set errno to [EINTR].
Consideration was also given to combining the two previous options, and setting errno to [EINTR] while returning a short count. However, not only is there no existing practice that implements this, it is also contradictory to the idea that when errno is set, the function responsible shall return -1.
This volume of POSIX.1‐2017 intentionally does not specify any pread() errors related to pipes, FIFOs, and sockets other than [ESPIPE].
fcntl(), ioctl(), lseek(), open(), pipe(), readv()
The Base Definitions volume of POSIX.1‐2017, Chapter 11, General Terminal Interface, <stropts.h>, <sys_uio.h>, <unistd.h>
GIT-COAUTHOR(1)                    Git Extras                    GIT-COAUTHOR(1)
git-coauthor - Add a co-author to the last commit
git-coauthor <co-author> <co-author-email>
Add a co-author to the last commit
<co-author>
The username of the co-author you want to add.
<co-author-email>
The email address of the author you want to add.
$ git coauthor user user@email.com
Written by Jacob Herrington jacobherringtondeveloper@gmail.com
VAGRANT(1)                        User Commands                       VAGRANT(1)
Vagrant - Tool for building and distributing virtualized development environments.
vagrant [-v] [-h] command [<args>]
Vagrant provides the framework and configuration format to create and manage complete portable development environments. These development environments can live on your computer or in the cloud, and are portable between Windows, Mac OS X, and Linux.
-v, --version Print the version and exit.
Available subcommands: box    manages boxes: installation, removal, etc.
destroy stops and deletes all traces of the vagrant machine
halt   stops the vagrant machine
help   shows the help for a subcommand
init   initializes a new Vagrant environment by creating a Vagrantfile
package packages a running vagrant environment into a box
plugin manages plugins: install, uninstall, update, etc.
provision provisions the vagrant machine
reload restarts vagrant machine, loads new Vagrantfile configuration
resume resume a suspended vagrant machine
ssh    connects to machine via SSH
ssh-config outputs OpenSSH valid configuration to connect to the machine
status outputs status of the vagrant machine
suspend suspends the machine
up     starts and provisions the vagrant environment
Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
For help on any individual command run vagrant COMMAND -h
GIT-REAUTHOR(1)                    Git Extras                    GIT-REAUTHOR(1)
git-reauthor - Rewrite history to change author´s identity
git reauthor [<options>]
Lets you replace the author and/or committer identities in commits and tags.
The command goes through all existing commits and tags in all local branches to selectively modify the identities present in those objects. All the other information such as dates, messages,.. are preserved.
You can rewrite all the identities in the commits and tags objects by using the --all flag, or only replace the identities whose email matches the value of the --old-email option. It is also possible to limit the rewrite to a certain type of identity: the author or the committer identity. By default, both of them are affected. For each of those identities to update, the command will replace the name and/or email with the new correct values as defined via the options. If the new identity name to set is not defined, the current one will be kept (and vice-versa with the email).
WARNING! This command rewrites history and as a result you will not able to push your branch to the remote without using the --force option. See more information with git help filter-branch.
Rewrite ALL identities in commits and tags.
-c, --use-config
Define correct values from user Git config Values of --correct-email and --correct-name options take precedence over the ones from the config if specified as well
-e, --correct-email <email>
Define the correct email to set Empty email ´´ is allowed
-n, --correct-name <name>
Define the correct name to set Empty name ´´ is not allowed
-o, --old-email <email>
Rewrite identities matching old email in commits and tags Empty email ´´ is allowed
-t, --type <id>
Define the type of identities affected by the rewrite Possible type identifiers are: author, committer, both (default)
Replace the personal email and name of Jack to his work ones
$ git reauthor --old-email jack@perso.me --correct-email jack@work.com --correct-name ´Jack Foobar´
Replace the email and name of Jack to the ones defined in the Git config
$ git reauthor --old-email jack@perso.me --use-config
Replace only the email of Jack (keep the name already used)
$ git reauthor --old-email jack@perso --correct-email jack@perso.me
Change only the committer email of Jack (keep the author email already used)
$ git reauthor --old-email jack@perso.me --correct-email jack@work.com --type committer
Set Jack´s identity as the only one of the whole repository
$ git reauthor --all --correct-email jack@perso.me --correct-name Jack
Set Jack as the only committer of the whole repository (keeps authors)
$ git reauthor --all --correct-email jack@perso.me --correct-name Jack --type committer
Written by Damien Tardy-Panis <damien@tardypad.me>
steamcmd(6)                       Games Manual                       steamcmd(6)
steamcmd - Command-line interface for Valve's Steam
for interactive mode, or either
steamcmd [+<action 1>] [+<action 2>] [...]
steamcmd +runscript <script>.txt
for automated mode.
Steam (http://www.steampowered.com) is a software content delivery system developed by Valve software (http://www.valvesoftware.com).  There is some free software available, but for the most part the content delivered is non-free.
The Steam Console Client or SteamCMD is a command-line version of the Steam client. Its primary use is to install and update various dedicated servers available on Steam using a command-line interface.
Some of the most useful options:
+runscript run an external script.
+login user pass provide Steam credentials
+@sSteamCmdForcePlatformType windows download Windows-only games on Linux
+app_update <n> download game number <n>
+force_install_dir <dir> install the game somewhere else than in ~/.steam/SteamApps/common
+quit  end steamcmd session. Without this the tool will remain in interactive mode.
"steamcmd +@sSteamCmdForcePlatformType windows +login "$USER" "$PASS" +app_update 2310 +quit"
will dowload Quake1 in ~/.steam/SteamApps/common/Quake
The number can be found in the game page's url: http://store.steampowered.com/app/2310/ .
The original runtime is stored in /usr/lib/games/steam . A copy is made in ~/.steam/steamcmd the first time steamcmd is ran. steamcmd will then try to update itself each time it is started.
This copy will remain even after the steamcmd has been purged and must be manually removed.
/usr/share/doc/steamcmd/steamcmdcommands.txt.gz for a complete list of commands.
Copyright Â© 2015 Alexandre Detiste <alexandre@detiste.be> This man page was written for the Debian project, but may be used by others.
TSORT(1)                          User Commands                         TSORT(1)
tsort - perform topological sort
tsort [OPTION] [FILE]
Write totally ordered list consistent with the partial ordering in FILE.
Written by Mark Kettenis.
Full documentation <https://www.gnu.org/software/coreutils/tsort> or available locally via: info '(coreutils) tsort invocation'
lp(1)                             OpenPrinting                             lp(1)
lp - print files
lp [ -E ] [ -U username ] [ -c ] [ -d destination[/instance] ] [ -h hostname[:port] ] [ -m ] [ -n num-copies ] [ -o option[=value] ] [ -q priority ] [ -s ] [ -t title ] [ -H handling ] [ -P page-list ] [ -- ] [ file(s) ] lp [ -E ] [ -U username ] [ -c ] [ -h hostname[:port] ] [ -i job-id ] [ -n num-copies ] [ -o option[=value] ] [ -q priority ] [ -t title ] [ -H handling ] [ -P page-list ]
lp submits files for printing or alters a pending job.  Use a filename of "-" to force printing from the standard input.
The following options are recognized by lp:
--   Marks the end of options; use this to print a file whose name begins with a dash (-).
-U username Specifies the username to use when connecting to the server.
-c   This option is provided for backwards-compatibility only. On systems that support it, this option forces the print file to be copied to the spool directory before printing.  In CUPS, print files are always sent to the scheduler via IPP which has the same effect.
-d destination Prints files to the named printer.
-h hostname[:port] Chooses an alternate server.
-i job-id Specifies an existing job to modify.
-m   Sends an email when the job is completed.
-n copies Sets the number of copies to print.
-o "name=value [ ... name=value ]" Sets one or more job options.  See "COMMON JOB OPTIONS" below.
-q priority Sets the job priority from 1 (lowest) to 100 (highest).  The default priority is 50.
-s   Do not report the resulting job IDs (silent mode.)
-t "name" Sets the job name.
-H hh:mm
-H hold
-H immediate
-H restart
-H resume Specifies when the job should be printed.  A value of immediate will print the file immediately, a value of hold will hold the job indefinitely, and a UTC time value (HH:MM) will hold the job until the specified UTC (not local) time.  Use a value of resume with the -i option to resume a held job.  Use a value of restart with the -i option to restart a completed job.
-P page-list Specifies which pages to print in the document.  The list can contain a list of numbers and ranges (#-#) separated by commas, e.g., "1,3-5,16".  The page numbers refer to the output pages and not the document's original pages - options like "number-up" can affect the numbering of the pages.
Unlike the System V printing system, CUPS allows printer names to contain any printable character except SPACE, TAB, "/", or "#".  Also, printer and class names are not case-sensitive.
The -q option accepts a different range of values than the Solaris lp command, matching the IPP job priority values (1-100, 100 is highest priority) instead of the Solaris values (0-39, 0 is highest priority).
lp -n 2 filename
lp -d foo -o media=legal -o sides=two-sided-long-edge filename
Print a presentation document 2-up to a printer called "bar":
lp -d bar -o number-up=2 filename
cancel(1), lpadmin(8), lpoptions(1), lpq(1), lpr(1), lprm(1), lpstat(1), CUPS Online Help (http://localhost:631/help)
GIT-BUG(1)                         Git Extras                         GIT-BUG(1)
git-bug - Create bug branch
git-bug [-r|--remote [remote_name]] [finish] <name>
Create the given bug branch
<finish>
Merge and delete the bug branch.
<-r
<name>
The name of the bug branch.
$ git bug bug-123456 `...` $ git commit -m "Some changes" `...` $ git checkout master $ git bug finish bug-123456
$ git bug -r 12345
Written by Jesus Espino <jespinog@gmail.com> Modified by Mark Pitman <mark.pitman@gmail.com>
KAFKACAT(1)                BSD General Commands Manual               KAFKACAT(1)
kafkacat â€” generic producer and consumer for Apache Kafka
kafkacat -C | -P | -L -t topic [-p partition] -b brokers [, ...] [-D delim] [-K delim] [-c cnt] [-X list] [-X prop=val] [-X dump] [-d dbg [, ...]] [-q] [-v] [-Z] [specific options] kafkacat -C [generic options] [-o offset] [-e] [-O] [-u] [-J] [-f fmtstr] kafkacat -P [generic options] [-z snappy | gzip] [-p -1] [file [...]] kafkacat -L [generic options] [-t topic]
kafkacat is a generic non-JVM producer and consumer for Apache Kafka 0.8, think of it as a netcat for Kafka.
In producer mode ( -P ), kafkacat reads messages from stdin, delimited with a configurable delimeter and produces them to the provided Kafka cluster, topic and partition. In consumer mode ( -C ), kafkacat reads messages from a topic and partition and prints them to stdout using the configured message delimiter.
If neither -P or -C are specified kafkacat attempts to figure out the mode automatically based on stdin/stdout tty types.
kafkacat also features a metadata list mode ( -L ), to display the current state of the Kafka cluster and its topics and partitions.
For a more extensive help and some simple examples, run kafkacat with -h flag.
FLEX(1)                      General Commands Manual                     FLEX(1)
flex - fast lexical analyzer generator
flex [-bcdfhilnpstvwBFILTV78+? -C[aefFmr] -ooutput -Pprefix -Sskeleton] [--help --version] [filename ...]
This manual describes flex, a tool for generating programs that perform pattern-matching on text.  The manual includes both tutorial and reference sections:
Description a brief overview of the tool
Some Simple Examples
Format Of The Input File
Patterns the extended regular expressions used by flex
How The Input Is Matched the rules for determining what has been matched
Actions how to specify what to do when a pattern is matched
The Generated Scanner details regarding the scanner that flex produces; how to control the input source
Start Conditions introducing context into your scanners, and managing "mini-scanners"
Multiple Input Buffers how to manipulate multiple input sources; how to scan from strings instead of files
End-of-file Rules special rules for matching the end of the input
Miscellaneous Macros a summary of macros available to the actions
Values Available To The User a summary of values available to the actions
Interfacing With Yacc connecting flex scanners together with yacc parsers
Options flex command-line options, and the "%option" directive
Performance Considerations how to make your scanner go as fast as possible
Generating C++ Scanners the (experimental) facility for generating C++ scanner classes
Incompatibilities With Lex And POSIX how flex differs from AT&T lex and the POSIX lex standard
Diagnostics those error messages produced by flex (or scanners it generates) whose meanings might not be apparent
Files files used by flex
Deficiencies / Bugs known problems with flex
See Also other documentation, related tools
Author includes contact information
flex is a tool for generating scanners: programs which recognized lexical patterns in text.  flex reads the given input files, or its standard input if no file names are given, for a description of a scanner to generate.  The description is in the form of pairs of regular expressions and C code, called rules. flex generates as output a C source file, lex.yy.c, which defines a routine yylex().  This file is compiled and linked with the -lfl library to produce an executable.  When the executable is run, it analyzes its input for occurrences of the regular expressions.  Whenever it finds one, it executes the corresponding C code.
First some simple examples to get the flavor of how one uses flex.  The following flex input specifies a scanner which whenever it encounters the string "username" will replace it with the user's login name:
%% username    printf( "%s", getlogin() );
By default, any text not matched by a flex scanner is copied to the output, so the net effect of this scanner is to copy its input file to its output with each occurrence of "username" expanded.  In this input, there is just one rule.  "username" is the pattern and the "printf" is the action.  The "%%" marks the beginning of the rules.
Here's another simple example:
int num_lines = 0, num_chars = 0;
%% \n      ++num_lines; ++num_chars; .       ++num_chars;
%% main() { yylex(); printf( "# of lines = %d, # of chars = %d\n", num_lines, num_chars ); }
This scanner counts the number of characters and the number of lines in its input (it produces no output other than the final report on the counts).  The first line declares two globals, "num_lines" and "num_chars", which are accessible both inside yylex() and in the main() routine declared after the second "%%".  There are two rules, one which matches a newline ("\n") and increments both the line count and the character count, and one which matches any character other than a newline (indicated by the "." regular expression).
A somewhat more complicated example:
/* scanner for a toy Pascal-like language */
%{ /* need this for the call to atof() below */ #include <math.h> %}
DIGIT    [0-9] ID       [a-z][a-z0-9]*
{DIGIT}+    { printf( "An integer: %s (%d)\n", yytext, atoi( yytext ) ); }
{DIGIT}+"."{DIGIT}*        { printf( "A float: %s (%g)\n", yytext, atof( yytext ) ); }
if|then|begin|end|procedure|function        { printf( "A keyword: %s\n", yytext ); }
{ID}        printf( "An identifier: %s\n", yytext );
"+"|"-"|"*"|"/"   printf( "An operator: %s\n", yytext );
"{"[^}\n]*"}"     /* eat up one-line comments */
[ \t\n]+          /* eat up whitespace */
.           printf( "Unrecognized character: %s\n", yytext );
main( argc, argv ) int argc; char **argv; { ++argv, --argc;  /* skip over program name */ if ( argc > 0 ) yyin = fopen( argv[0], "r" ); else yyin = stdin;
yylex(); }
This is the beginnings of a simple scanner for a language like Pascal. It identifies different types of tokens and reports on what it has seen.
The details of this example will be explained in the following sections.
The flex input file consists of three sections, separated by a line with just %% in it:
definitions %% rules %% user code
The definitions section contains declarations of simple name definitions to simplify the scanner specification, and declarations of start conditions, which are explained in a later section.
Name definitions have the form:
name definition
The "name" is a word beginning with a letter or an underscore ('_') followed by zero or more letters, digits, '_', or '-' (dash).  The definition is taken to begin at the first non-white-space character following the name and continuing to the end of the line.  The definition can subsequently be referred to using "{name}", which will expand to "(definition)".  For example,
defines "DIGIT" to be a regular expression which matches a single digit, and "ID" to be a regular expression which matches a letter followed by zero-or-more letters-or-digits.  A subsequent reference to
{DIGIT}+"."{DIGIT}*
is identical to
([0-9])+"."([0-9])*
and matches one-or-more digits followed by a '.' followed by zero-or-more digits.
The rules section of the flex input contains a series of rules of the form:
pattern   action
where the pattern must be unindented and the action must begin on the same line.
See below for a further description of patterns and actions.
Finally, the user code section is simply copied to lex.yy.c verbatim.  It is used for companion routines which call or are called by the scanner. The presence of this section is optional; if it is missing, the second %% in the input file may be skipped, too.
In the definitions and rules sections, any indented text or text enclosed in %{ and %} is copied verbatim to the output (with the %{}'s removed). The %{}'s must appear unindented on lines by themselves.
In the rules section, any indented or %{} text appearing before the first rule may be used to declare variables which are local to the scanning routine and (after the declarations) code which is to be executed whenever the scanning routine is entered.  Other indented or %{} text in the rule section is still copied to the output, but its meaning is not well-defined and it may well cause compile-time errors (this feature is present for POSIX compliance; see below for other such features).
In the definitions section (but not in the rules section), an unindented comment (i.e., a line beginning with "/*") is also copied verbatim to the output up to the next "*/".
The patterns in the input are written using an extended set of regular expressions.  These are:
x          match the character 'x' .          any character (byte) except newline [xyz]      a "character class"; in this case, the pattern matches either an 'x', a 'y', or a 'z' [abj-oZ]   a "character class" with a range in it; matches an 'a', a 'b', any letter from 'j' through 'o', or a 'Z' [^A-Z]     a "negated character class", i.e., any character but those in the class.  In this case, any character EXCEPT an uppercase letter. [^A-Z\n]   any character EXCEPT an uppercase letter or a newline r*         zero or more r's, where r is any regular expression r+         one or more r's r?         zero or one r's (that is, "an optional r") r{2,5}     anywhere from two to five r's r{2,}      two or more r's r{4}       exactly 4 r's {name}     the expansion of the "name" definition (see above) "[xyz]\"foo" the literal string: [xyz]"foo \X         if X is an 'a', 'b', 'f', 'n', 'r', 't', or 'v', then the ANSI-C interpretation of \x. Otherwise, a literal 'X' (used to escape operators such as '*') \0         a NUL character (ASCII code 0) \123       the character with octal value 123 \x2a       the character with hexadecimal value 2a (r)        match an r; parentheses are used to override precedence (see below)
rs         the regular expression r followed by the regular expression s; called "concatenation"
r|s        either an r or an s
r/s        an r but only if it is followed by an s.  The text matched by s is included when determining whether this rule is the "longest match", but is then returned to the input before the action is executed.  So the action only sees the text matched by r.  This type of pattern is called trailing context". (There are some combinations of r/s that flex cannot match correctly; see notes in the Deficiencies / Bugs section below regarding "dangerous trailing context".) ^r         an r, but only at the beginning of a line (i.e., which just starting to scan, or right after a newline has been scanned). r$         an r, but only at the end of a line (i.e., just before a newline).  Equivalent to "r/\n".
Note that flex's notion of "newline" is exactly whatever the C compiler used to compile flex interprets '\n' as; in particular, on some DOS systems you must either filter out \r's in the input yourself, or explicitly use r/\r\n for "r$".
r       an r, but only in start condition s (see below for discussion of start conditions) <s1,s2,s3>r same, but in any of start conditions s1, s2, or s3 <*>r       an r in any start condition, even an exclusive one.
<<EOF>>    an end-of-file <s1,s2><<EOF>> an end-of-file when in start condition s1 or s2
Note that inside of a character class, all regular expression operators lose their special meaning except escape ('\') and the character class operators, '-', ']', and, at the beginning of the class, '^'.
The regular expressions listed above are grouped according to precedence, from highest precedence at the top to lowest at the bottom.  Those grouped together have equal precedence.  For example,
foo|bar*
is the same as
(foo)|(ba(r*))
since the '*' operator has higher precedence than concatenation, and concatenation higher than alternation ('|').  This pattern therefore matches either the string "foo" or the string "ba" followed by zero-or- more r's.  To match "foo" or zero-or-more "bar"'s, use:
foo|(bar)*
and to match zero-or-more "foo"'s-or-"bar"'s:
(foo|bar)*
In addition to characters and ranges of characters, character classes can also contain character class expressions.  These are expressions enclosed inside [: and :] delimiters (which themselves must appear between the '[' and ']' of the character class; other elements may occur inside the character class, too).  The valid expressions are:
[:alnum:] [:alpha:] [:blank:] [:cntrl:] [:digit:] [:graph:] [:lower:] [:print:] [:punct:] [:space:] [:upper:] [:xdigit:]
These expressions all designate a set of characters equivalent to the corresponding standard C isXXX function.  For example, [:alnum:] designates those characters for which isalnum() returns true - i.e., any alphabetic or numeric.  Some systems don't provide isblank(), so flex defines [:blank:] as a blank or a tab.
For example, the following character classes are all equivalent:
[[:alnum:]] [[:alpha:][:digit:]] [[:alpha:][0-9]] [a-zA-Z0-9]
If your scanner is case-insensitive (the -i flag), then [:upper:] and [:lower:] are equivalent to [:alpha:].
Some notes on patterns:
-      A negated character class such as the example "[^A-Z]" above will match a newline unless "\n" (or an equivalent escape sequence) is one of the characters explicitly present in the negated character class (e.g., "[^A-Z\n]").  This is unlike how many other regular expression tools treat negated character classes, but unfortunately the inconsistency is historically entrenched. Matching newlines means that a pattern like [^"]* can match the entire input unless there's another quote in the input.
-      A rule can have at most one instance of trailing context (the '/' operator or the '$' operator).  The start condition, '^', and "<<EOF>>" patterns can only occur at the beginning of a pattern, and, as well as with '/' and '$', cannot be grouped inside parentheses.  A '^' which does not occur at the beginning of a rule or a '$' which does not occur at the end of a rule loses its special properties and is treated as a normal character.
The following are illegal:
foo/bar$ <sc1>foo<sc2>bar
Note that the first of these, can be written "foo/bar\n".
The following will result in '$' or '^' being treated as a normal character:
foo|(bar$) foo|^bar
If what's wanted is a "foo" or a bar-followed-by-a-newline, the following could be used (the special '|' action is explained below):
foo      | bar$     /* action goes here */
A similar trick will work for matching a foo or a bar-at-the- beginning-of-a-line.
When the generated scanner is run, it analyzes its input looking for strings which match any of its patterns.  If it finds more than one match, it takes the one matching the most text (for trailing context rules, this includes the length of the trailing part, even though it will then be returned to the input).  If it finds two or more matches of the same length, the rule listed first in the flex input file is chosen.
Once the match is determined, the text corresponding to the match (called the token) is made available in the global character pointer yytext, and its length in the global integer yyleng.  The action corresponding to the matched pattern is then executed (a more detailed description of actions follows), and then the remaining input is scanned for another match.
If no match is found, then the default rule is executed: the next character in the input is considered matched and copied to the standard output.  Thus, the simplest legal flex input is:
which generates a scanner that simply copies its input (one character at a time) to its output.
Note that yytext can be defined in two different ways: either as a character pointer or as a character array.  You can control which definition flex uses by including one of the special directives %pointer or %array in the first (definitions) section of your flex input.  The default is %pointer, unless you use the -l lex compatibility option, in which case yytext will be an array.  The advantage of using %pointer is substantially faster scanning and no buffer overflow when matching very large tokens (unless you run out of dynamic memory).  The disadvantage is that you are restricted in how your actions can modify yytext (see the next section), and calls to the unput() function destroys the present contents of yytext, which can be a considerable porting headache when moving between different lex versions.
The advantage of %array is that you can then modify yytext to your heart's content, and calls to unput() do not destroy yytext (see below). Furthermore, existing lex programs sometimes access yytext externally using declarations of the form: extern char yytext[]; This definition is erroneous when used with %pointer, but correct for %array.
%array defines yytext to be an array of YYLMAX characters, which defaults to a fairly large value.  You can change the size by simply #define'ing YYLMAX to a different value in the first section of your flex input.  As mentioned above, with %pointer yytext grows dynamically to accommodate large tokens.  While this means your %pointer scanner can accommodate very large tokens (such as matching entire blocks of comments), bear in mind that each time the scanner must resize yytext it also must rescan the entire token from the beginning, so matching such tokens can prove slow.  yytext presently does not dynamically grow if a call to unput() results in too much text being pushed back; instead, a run-time error results.
Also note that you cannot use %array with C++ scanner classes (the c++ option; see below).
Each pattern in a rule has a corresponding action, which can be any arbitrary C statement.  The pattern ends at the first non-escaped whitespace character; the remainder of the line is its action.  If the action is empty, then when the pattern is matched the input token is simply discarded.  For example, here is the specification for a program which deletes all occurrences of "zap me" from its input:
%% "zap me"
(It will copy all other characters in the input to the output since they will be matched by the default rule.)
Here is a program which compresses multiple blanks and tabs down to a single blank, and throws away whitespace found at the end of a line:
%% [ \t]+        putchar( ' ' ); [ \t]+$       /* ignore this token */
If the action contains a '{', then the action spans till the balancing '}' is found, and the action may cross multiple lines.  flex knows about C strings and comments and won't be fooled by braces found within them, but also allows actions to begin with %{ and will consider the action to be all the text up to the next %} (regardless of ordinary braces inside the action).
An action consisting solely of a vertical bar ('|') means "same as the action for the next rule."  See below for an illustration.
Actions can include arbitrary C code, including return statements to return a value to whatever routine called yylex().  Each time yylex() is called it continues processing tokens from where it last left off until it either reaches the end of the file or executes a return.
Actions are free to modify yytext except for lengthening it (adding characters to its end--these will overwrite later characters in the input stream).  This however does not apply when using %array (see above); in that case, yytext may be freely modified in any way.
Actions are free to modify yyleng except they should not do so if the action also includes use of yymore() (see below).
There are a number of special directives which can be included within an action:
-      ECHO copies yytext to the scanner's output.
-      BEGIN followed by the name of a start condition places the scanner in the corresponding start condition (see below).
-      REJECT directs the scanner to proceed on to the "second best" rule which matched the input (or a prefix of the input).  The rule is chosen as described above in "How the Input is Matched", and yytext and yyleng set up appropriately.  It may either be one which matched as much text as the originally chosen rule but came later in the flex input file, or one which matched less text.  For example, the following will both count the words in the input and call the routine special() whenever "frob" is seen:
int word_count = 0; %%
frob        special(); REJECT; [^ \t\n]+   ++word_count;
Without the REJECT, any "frob"'s in the input would not be counted as words, since the scanner normally executes only one action per token.  Multiple REJECT's are allowed, each one finding the next best choice to the currently active rule.  For example, when the following scanner scans the token "abcd", it will write "abcdabcaba" to the output:
%% a        | ab       | abc      | abcd     ECHO; REJECT; .|\n     /* eat up any unmatched character */
(The first three rules share the fourth's action since they use the special '|' action.)  REJECT is a particularly expensive feature in terms of scanner performance; if it is used in any of the scanner's actions it will slow down all of the scanner's matching.  Furthermore, REJECT cannot be used with the -Cf or -CF options (see below).
Note also that unlike the other special actions, REJECT is a branch; code immediately following it in the action will not be executed.
-      yymore() tells the scanner that the next time it matches a rule, the corresponding token should be appended onto the current value of yytext rather than replacing it.  For example, given the input "mega-kludge" the following will write "mega-mega-kludge" to the output:
%% mega-    ECHO; yymore(); kludge   ECHO;
First "mega-" is matched and echoed to the output.  Then "kludge" is matched, but the previous "mega-" is still hanging around at the beginning of yytext so the ECHO for the "kludge" rule will actually write "mega-kludge".
Two notes regarding use of yymore().  First, yymore() depends on the value of yyleng correctly reflecting the size of the current token, so you must not modify yyleng if you are using yymore().  Second, the presence of yymore() in the scanner's action entails a minor performance penalty in the scanner's matching speed.
-      yyless(n) returns all but the first n characters of the current token back to the input stream, where they will be rescanned when the scanner looks for the next match.  yytext and yyleng are adjusted appropriately (e.g., yyleng will now be equal to n ). For example, on the input "foobar" the following will write out "foobarbar":
%% foobar    ECHO; yyless(3); [a-z]+    ECHO;
An argument of 0 to yyless will cause the entire current input string to be scanned again.  Unless you've changed how the scanner will subsequently process its input (using BEGIN, for example), this will result in an endless loop.
Note that yyless is a macro and can only be used in the flex input file, not from other source files.
-      unput(c) puts the character c back onto the input stream.  It will be the next character scanned.  The following action will take the current token and cause it to be rescanned enclosed in parentheses.
{ int i; /* Copy yytext because unput() trashes yytext */ char *yycopy = strdup( yytext ); unput( ')' ); for ( i = yyleng - 1; i >= 0; --i ) unput( yycopy[i] ); unput( '(' ); free( yycopy ); }
Note that since each unput() puts the given character back at the beginning of the input stream, pushing back strings must be done back-to-front.
An important potential problem when using unput() is that if you are using %pointer (the default), a call to unput() destroys the contents of yytext, starting with its rightmost character and devouring one character to the left with each call.  If you need the value of yytext preserved after a call to unput() (as in the above example), you must either first copy it elsewhere, or build your scanner using %array instead (see How The Input Is Matched).
Finally, note that you cannot put back EOF to attempt to mark the input stream with an end-of-file.
-      input() reads the next character from the input stream.  For example, the following is one way to eat up C comments:
%% "/*"        { register int c;
for ( ; ; ) { while ( (c = input()) != '*' && c != EOF ) ;    /* eat up text of comment */
if ( c == '*' ) { while ( (c = input()) == '*' ) ; if ( c == '/' ) break;    /* found the end */ }
if ( c == EOF ) { error( "EOF in comment" ); break; } } }
(Note that if the scanner is compiled using C++, then input() is instead referred to as yyinput(), in order to avoid a name clash with the C++ stream by the name of input.)
-      YY_FLUSH_BUFFER flushes the scanner's internal buffer so that the next time the scanner attempts to match a token, it will first refill the buffer using YY_INPUT (see The Generated Scanner, below).  This action is a special case of the more general yy_flush_buffer() function, described below in the section Multiple Input Buffers.
-      yyterminate() can be used in lieu of a return statement in an action.  It terminates the scanner and returns a 0 to the scanner's caller, indicating "all done".  By default, yyterminate() is also called when an end-of-file is encountered. It is a macro and may be redefined.
The output of flex is the file lex.yy.c, which contains the scanning routine yylex(), a number of tables used by it for matching tokens, and a number of auxiliary routines and macros.  By default, yylex() is declared as follows:
int yylex() { ... various definitions and the actions in here ... }