STROKE

NAME

SYNOPSIS

stroke [ -s | -r | -b ] [-l] [-c] [-f] ARGUMENT FILE...

stroke [ -i ] [-l] [-c] [-f] FILE...  

DESCRIPTION

Sometimes it is desirable to exclusively change very specific components of a file's modification, access, or change time; however, the method provided by the conventional touch(1) utility appears inadequate for this basic task. Moreover, easily modifying a file's change time is not possible at all.

Stroke offers a solution by providing a user with an advanced command line interface which allows her to utilize an extensive syntax to dynamically specify certain date and time components to be altered.

All in all stroke can be seen as a potent alternative to the conventional touch(1) utility that leaves a user with more options.  

OPTIONS

-s, -stamp

ARGUMENT must be by supplied to be a time stamp of the form [[CC]YY]MMDDhhmm[.ss][:SELECTOR] (for a more detailed description see TIME STAMPS below).

-r, -reference

If given, ARGUMENT stands for a reference file whose time and date is to be applied unchanged to FILE.

-l, -symlinks

If FILE or reference file (in case of `-r') refer to a symbolic link, read access, modification and change time from that link. Also, if FILE refers to a symbolic link, alter that link's modification, access, and change time. Note that change time will only be modified if `-c' is given (see below).

-c, -ctime

In all of the changes done to a file its change time is only effectively altered if explicitly required so; this can be achieved by specifying this option on the command line. It can mutually be applied with other options that implicate immanent alterations to a file's time or date values. Note that giving this option might necessitate super user privileges.

-p, -preserve

When altering modification or access time, prevent the change time from being implicitly altered too (for more details see NOTES: Change time preservation). Root privileges might be required.

-i, -info

If this option is given, ARGUMENT must refer to a file about which modification, access, and change time information will be printed; in case of a symbolic link, additional information is related in the output.

Information whether daylight saving time is in effect is given by prepending a `+' for in effect, a `-' for not in effect, or a `?' for unknown to the string `dst' in parenthesis.

-b, -batch

Giving this option requires ARGUMENT to refer to a stroke batch file from which modifier expressions are to be read (for details on modifier expressions see BATCH FILES below).

-v, -verbose

Generate more verbose output; show what is internally done.

-q, -quiet

Do not output anything. Only return value to calling shell informs about success or failure (see RETURN VALUE below).

-h, -help

Print a succinct help message.

-version

Print program information

ARGUMENTS

The meaning of ARGUMENT may differ between three different things. Following is a list of what these are:

-s, -stamp

ARGUMENT is interpreted as a time stamp. For more details see TIME STAMPS below.

-r, -reference

If given, ARGUMENT must refer to a file whose date and time values will yield those of FILE.

-b, -batch

ARGUMENT must refer to stroke batch file (see BATCH FILES below).

None (default)

By default, ARGUMENT is considered to be a modifier expression list (see MODIFIERS below). Using modifiers to dynamically set date and time values might be considered the main feature of stroke.

MODIFIERS

In any usual case, that is when `-s, -stamp' or `-r, -reference' are not given, ARGUMENT is understood to be a modifier expression list to which a well-defined syntax and semantics rule-set (grammar) applies.

This grammar can be expressed in greater detail by representing it using the following EBNF notation:

(1) LIST = ARGUMENT =
( EXPRESSION , { "," | ";" , EXPRESSION } ) | "-" ;
(2) EXPRESSION =
IDENTIFIER , { "=" , IDENTIFIER }, "=",
VALUE | MODULATOR | IDENTIFIER ;
(3) IDENTIFIER =
 QUALIFIER , SPECIFIER ;
(4) QUALIFIER =
"m" | "a" | "c" ;
(5) SPECIFIER =
"Y" | "M" | "D" | "h" | "m" | "s" | "l";
(6) MODULATOR =
"+" | "-" , "+" | "-" | VALUE ;
(7) VALUE =
"0" | DIGIT, { DIGIT | "0" } ;
(8) DIGIT =
"1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

(1) Modifier expression list

The non-terminal symbol LIST stands for the actual modifier expression list that is given on the command line as ARGUMENT, or is supplied through the the input stream stdin(3) in case of ARGUMENT being `-', or is read from a batch file in case of `-b, -batch' being given.

(2) Modifier expressions

A modifier expression is a simple or chained assignment which - in its most basic form - consists of a time value identifier on the left, an equal sign, and a VALUE, MODULATOR, or another IDENTIFIER on the right.

During evaluation, a modifier expression expands into partial assignments in which each identifier to the left of the rightmost equal sign is singly assigned the rightmost integer, resolved identifier value, or modulator.

Should any of those partial assignments fail for whatever reason, the whole modifier expression is deemed invalid which in turn causes the entire modifier expression list to be invalidated.

(3) Identifiers

An identifier, being composed of qualifier and specifier, essentially represents or "identifies" a time or date value. There are identifiers for all components of modification, access, and change time.

(4) Qualifiers

Qualifiers essentially decide whether an identifier is part of the sets of time and date values for modification, access and change time.

(5) Specifiers

Specifiers govern about which time or date component is represented by an identifier. Their representations are fittingly chosen to match common associative mappings of single characters to date and time components.

The specifier "l" stands for daylight saving time whereby the values assignable range from 0 to 2. 0 means that daylight saving time should be neglected. Whether daylight saving time is seen as being in effect depends on the date itself as well as on your local time zone settings. A value of 1 indicates that daylight saving time is not in effect, 2, on the other hand, indicates that it is.

(6) Modulators

Modulators conveniently increment or decrement and identifier's associated time or date value; we say they "modulate" their identifier's value.

Modulators start with a PLUS `+' or MINUS `-' to indicate whether the concerning identifier's value is to be increased or decreased respectively. The following VALUE indicates by what amount the previously selected increment or decrement operation should be performed.

The shorthand `++' or `--' express that the value in question should be either incremented or decremented by a value of one.

(7), (8) Values and digits

A VALUE are all positive whole numbers including 0; they are composed of DIGITs.

An example for a complete modifier expression list LIST that abides by all of the above grammatical rules would be:

mY=aY=1996, mD=23, aD=-5, am=mm=cm=cs, am=mM=++ 

Note that in this example, "-5" is a modulator for the identifier "aD" and not an actual value.

Do also note that when giving LIST on the command line, spaces are probably interpreted as argument separators by your shell; hence they should be avoided or quotations marks should be applied.  

TIME STAMPS

[[CC]YY]MMDDhhmm[.ss][:SELECTOR]

That what is framed by `[' and `]' may or may not be given in a time stamp.

Values are generally given in pairs of two numeric values greater or equal to 0. A leading 0 becomes necessary if the desired date or time value is smaller than 10.

A SELECTOR lets you chooses whether modification, access or change time of FILE are to be set by applying the time stamp at hand. Valid SELECTORs are `m', `a', `c' or any unique combination thereof. Note that if not given, SELECTOR implicitly defaults to `m'.

For instance, a valid time stamp would be:

0005132305.07:am

Note that it is not required for FILE to exists when time stamps are used; that is because a time stamp - even in its most minimal form - provides a sufficient amount of information to assemble a valid date.

If the [[CC]YY] information is left out, the current year is assumed. If of this token, only [CC] is not given, the current century is assumed for the date assembled. If lastly [.ss] is not specified, the value for seconds is taken to be 0.  

BATCH FILES

As the name itself suggests are batch files intended to handle larger date and time value modification tasks, possibly also for a much larger number of files than just one or two.

Modifier expressions within a stroke batch file may be split into individual lines for readability; each of these lines should then end in a SEMICOLON `;'. Modifier expressions themselves, however, may again be separated by a simple COMMA ','.

Comments, introduced by a leading POUND SIGN `#' as well as empty lines are ignored.

A sample stroke batch file might thus look like this:

#
# Sample stroke batch file
# 

# Modify day values
mD = cD = 23, aD = 25;

# Increase all month values by one
mM = aM = cM = ++;

# Liken minutes to seconds
mm = cm = ms;

# Modify years
mY = 1994, cY = mY, cY = -2;

Although this example may seem somewhat concocted, an important insight into the core principles of modifier expressions can be gained from it.  

EXAMPLES

stroke -ctime cY=mY,cM=mM,cD=mD,ch=ah=mh <file>

Set a file's change time date components equal to those of its modification time. Moreover, set its change time and access time hour component equal to that of its modification time.

stroke -preserve mY=aY=++,mM=aM=-2 <file>

Increment a file's modification and access time year value by one and decrement its access and modification month value by 2. In all this, preserve the file's original change time. Root privileges might be necessary.

stroke -ctime mD=aD=cD=3 *.c

Changing the day component of modification, access and change time of all the `*.c' files in the current directory to 3.

stroke -force mM=23,mD=101 <file>

Normally, assigning month and date values erroneously as shown here would result in a failing date validation. But since `-force' is given, the faulty date given will be transfigured to a valid one.

stroke -c -s 0005132305.23:mac <file>

Setting a files modification, access, and change time to the date indicated by the time stamp given.

find -name *.jpg | xargs stroke mM=aM=3

Here the tools xargs(1) and find(1) are used to traverse the current directory tree. In this example, the month value of access and modification time of all `*.jpg' files in the current directory tree is changed to 3.

NOTES

Invocation

If FILE should be non-existent it gets created as an empty file; its time and date values are updated also. All of the this does also hold true if the options `-s, -stamp' or `-r, -reference' are given.

Consequently, modifier expressions in any fashion can only be applied to an already existing file.  

Change time

It is to be noted that in order for this to work root privileges might be necessary as is case with most systems.

Despite the fact of trying to circumvent clock skews, they often do arise when a file's change time is modified due to the method used for altering them - they seem somewhat inavoidable.  

Change time preservation

The most convenient method to remedy this automatic change time adaption is by giving the `-p, -preserve' option on the command line. Now, stroke attempts to preserve a file's change time beyond any alterations made to its modification or access time. Note that, as with `-c, -ctime', root privileges might also be required.  

Modulators

Here, on has to be cautioned: Although a modulator may seem fit for one of the partial assignments, an erroneous partial assignment will still result in invalidating the entire modifier expression.  

Batch files and stdin

(1) cat batch.file > stroke - <file>

(2) stroke -b batch.file <file>

Instead of specifying `-b, -batch', making use of stdin can have many more versatile applications however.  

Using `-f, -force'

Files

RETURN VALUE

If an error occurs, a positive-valued error code is returned, which, assuming stroke had been invoked with `-v, -verbose', is the same that got displayed at the end of the most recent error message.

In case the program execution becomes fatally interrupted, an immediate abortion will be the result; an error code is returned likewise.  

BUGS

A bug report should loosely contain the following information: a simple description of the fault and the situation in which it occurs, program output and resulting error code if appropriate, directions on how to reproduce the bug. The concerning error code may be obtained by rerunning with `-v, -verbose'.  

AUTHOR

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

ARGUMENTS

MODIFIERS

TIME STAMPS

BATCH FILES

EXAMPLES

NOTES

Invocation

Change time

Change time preservation

Modulators

Batch files and stdin

Using `-f, -force'

Files

RETURN VALUE

BUGS

AUTHOR

SEE ALSO