Section: User commands (1)
Updated: 05-24-2009
Index Return to Main Contents


stroke - Dynamically changing modification, access, and change time components  


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

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


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.  


-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.
Print program information


The default behavior of stroke is much like that of touch(1). By however having the ability to specify ARGUMENTs a great many more options are provided.

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.


Through modifiers it is possible to alter only very specific components of modification, access, or change time in a very organic way.

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:

( EXPRESSION , { "," | ";" , EXPRESSION } ) | "-" ;
"m" | "a" | "c" ;
"Y" | "M" | "D" | "h" | "m" | "s" | "l";
"+" | "-" , "+" | "-" | 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.  


Although not offering as much flexibility as modifiers do, time stamps are still a very convenient way of setting a date by means of a compact format that has the following form:


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:


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.  


If `-b, -batch' is given, ARGUMENT must refer to a batch file. Modifier expressions are then read from that file in much the same way they would be read from the command line if given as ARGUMENT.

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.  


A few practical examples shall illustrate the general use of stroke:
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.


This section attempts to complement this manual by providing additional information that cannot be fittingly related in other places.  


Upon invocation with no arguments other than its file argument, stroke updates the file's modification, access, and change time by setting them to the current time.

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

Even if change time alterations have been made through the use of modifiers, time stamps, or reference files, they are only then truly applied if the `-c, -ctime` option was given prior.

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

Note that when altering modification or access time, a file's change time is implicitly changing to the value of the time when this alteration was taking place too; this is so because the notion of change time reflects the time when any last changes were made to a file's inode, which, of course, is the case when changing its modification or access time.

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.  


When modulators appear on the right-hand side of a chained assignment they are partially assigned to and singly evaluated against each of the identifiers in the assignment.

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

Both methods of using batch files and having the ability to read modifier expressions from stdin are somewhat related to each other. Consider, for instance, the following two commands which yield the same result:

(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'

Having `-force' in effect during the evaluation of an assignment which would exceed the natural boundaries of the left-hand time or date value identifier will result in having the overall date normalized (e. g. mh=26 becomes mh=2 the next day).  


The notion of "file" does also intrinsically lend itself to the concept of "directory" in Unix which is why - in this manual - both are taken to be synonyms of each other.  


Upon successful completion stroke returns a value of 0 to the calling shell.

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.  


None the author is currently aware of. However, you are highly encouraged to help by reporting bugs to <>. You may also use the official bugtracker at SourceForge.

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'.  


GNU stroke as well as this manual have been written by Soeren Wellhoefer <>  





Change time
Change time preservation
Batch files and stdin
Using `-f, -force'

This document was created by man2html, using the manual pages.
Time: 19:42:11 GMT, March 16, 2010