.TH EXIFTIME 1
.\"
.\" Copyright (c) 2004-2007, Eric M. Johnston <[email protected]>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed by Eric M. Johnston.
.\" 4. Neither the name of the author nor the names of any co-contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $Id: exiftime.1,v 1.2 2007/12/16 02:19:25 ejohnst Exp $
.\"
.SH NAME
.B exiftime
\- display or adjust date & time Exif tags; list files ordered by their
Exif date & time tags
.SH SYNOPSIS
.B exiftime
.RB [ \-filqw ]
.RB [ \-s
.IR delim ]
.RB [ \-t [ acdg ]]
.RB [ \-v [   | \- ] \fIval [ ymwdHMS ]]
.I file ...
.SH DESCRIPTION
When invoked without arguments, the
.B exiftime
utility displays the Exif date and time tags contained in each input
.I file
to the standard output.  Otherwise, depending on the options specified,
.B exiftime
will operate on only the chosen tags, will adjust the date and time,
will write an adjusted time to each
.IR file ,
or will list each
.I file
in ascending order by date and time.

Most digital cameras include one or more date and time tags in the Exif
data added to the image files they produce.  These tags are:
.IP "Image Created" 4
The date and time the image was created or changed.  This is the most common tag.
.IP "Image Generated" 4
The date and time the original image data was generated (i.e., when picture was taken).
.IP "Image Digitized" 4
The date and time the image was stored as digital data.
.PP
The format for these tags is "YYYY:MM:DD HH:MM:SS" with the time shown in
24-hour format.  The
.B exiftime
utility cannot add a tag if it does not already exist in
.IR file .

By default,
.B exiftime
will simply print out any of the three date and time flags in each input
.IR file .
The
.B -l
flag
will produce a listing of each input
.I file
in date/time order, suitable for use in
further image processing (e.g., production of a Web catalog) when filename
ordering is not useful.

The
.B -v
flag may be used to vary, or adjust, dates and times.  When used with the
.B -w
flag, which writes the adjusted date and time to each input
.IR file ,
one may, for example, process a batch of files to adjust for a camera's
incorrectly set clock.
.SH OPTIONS
.IP -f
Write adjusted date and time tags without prompting for confirmation.
.IP -i
Output a prompt to standard error before overwriting a date and time tag with
the adjusted value.  If the response from the standard input begins with 'y'
or 'Y', the tag is overwritten.  This option is default behavior.
.IP -l
List each input
.I file
in ascending order by timestamp.  By default, it uses the Image Created tag.
In the absence of an Image Created tag, first Image Generated then Image
Digitized are used.  Alternatively, the
.B -t
flag may be used to specify the timestamp preference for ordering.  If no
date and time tags are present, the OS's epoch is used.  This flag
overrides all others but the
.B -t
flag.
.IP -q
Do not output details of a date and time adjustment to standard out when
using the
.B -w
flag.
.IP -s
Separate field name and value with the string
.IR delim  .
The default is ': '.
.IP -t
Select the date and time tags for display or adjustment when followed by one
or more of
.B a
(all tags),
.B c
(Image Created),
.B d
(Image Digitized), or 
.B g
(Image Generated).
.IP -v
Adjust the date and time tags' second, minute, hour, month day, week day,
month or year according to
.IR val .
If
.I val
is preceded with a plus or minus sign, the date is adjusted forwards or
backwards according to the remaining string; otherwise the relevant part of
the date is set.  The date can be adjusted as many times as required using
these flags.  Flags are processed in the order given.

When providing an absolute value (rather than a relative adjustment),
seconds are in the range 0-59, minutes are in the range 0-59, hours are
in the range 0-23, month days are in the range 1-31, week days are in the
range 0-6 (Sun-Sat), months are in the range 1-12 (Jan-Dec) and years are in
the range 80-38 or 1980-2038.

If
.I val
is numeric, one of either
.BR y ,
.BR m ,
.BR w ,
.BR d ,
.BR H ,
.BR M ", or "
.B S
must be used to specify which part of the date is to be adjusted.

The week day or month may be specified using a name rather than a number.
If a name is used with the plus (or minus) sign, the date will be put forwards
(or backwards) to the next (previous) date that matches the given week day
or month.  This will not adjust the date, if the given week day or month is
the same as the current one.

When the date is adjusted to a specific value that doesn't actually exist
(for example March 26, 1:30 BST 2000 in the Europe/London timezone),
the date will be silently adjusted forwards in units of one hour until it
reaches a valid time.  When the date is adjusted to a specific value that
occurs twice (for example October 29, 1:30 2000), the resulting timezone will
be set so that the date matches the earlier of the two times.  In all cases,
daylight savings time considerations are ignored.

Refer to the examples below for further details.
.IP -w
Write the adjusted date and time tags.  By default, any of the three date and
time tags present in the file are adjusted; otherwise, only those specified
with the
.B -t
flag are adjusted.
.SH EXAMPLES
The command
.IP
.nf
exiftime example1.jpg
.fi
.PP
will display:
.IP
.nf
Image Created: 2003:09:12 17:05:37
Image Generated: 2003:09:12 17:05:37
Image Digitized: 2003:09:12 17:05:37
.fi
.PP
The command
.IP
.nf
exiftime \-tcd example1.jpg
.fi
.PP
will display:
.IP
.nf
Image Created: 2003:09:12 17:05:37
Image Digitized: 2003:09:12 17:05:37
.fi
.PP
The command
.IP
.nf
exiftime \-v 3H example1.jpg
.fi
.PP
will adjust each time forward by three hours and display:
.IP
.nf
Image Created: 2003:09:12 20:05:37
Image Generated: 2003:09:12 20:05:37
Image Digitized: 2003:09:12 20:05:37
.fi
.PP
The command
.IP
.nf
exiftime \-v 5d \-v\-7M \-fw \-tg *.jpg
.fi
.PP
will adjust the date ahead five days and the time back seven minutes and
write the adjusted date and time to the Image Generated tag without a prompt
for confirmation for all files that match "*.jpg".  It displays:
.IP
.nf
example1.jpg:
Image Generated: 2003:09:12 17:05:37 -> 2003:09:17 16:58:37

example2.jpg:
Image Generated: 2004:01:22 17:07:02 -> 2004:01:27 17:00:02
.fi
.PP
The command
.IP
.nf
exiftime \-l \-tdg *.jpg
.fi
.PP
will list all files that match "*.jpg", one per line, in ascending timestamp
order.  It'll attempt to use the following timestamp values, in order: Image
Digitized, Image Generated, Image Created, and, finally, the OS's epoch.
.SH DIAGNOSTICS
The
.B exiftime
utility exits 0 on success and 1 if an error occurs.
.SH "SEE ALSO"
exiftags(1), exifcom(1)
.SH STANDARDS
The
.B exiftime
utility was developed using the 2003 draft Exif standard, version 2.21
(http://tsc.jeita.or.jp/).
.SH BUGS
Does not support the Exif tags SubsecTime, SubsecTimeOriginal, or
SubsecTimeDigitized.  Does not support manufacturer-specific date and time
tags.
.SH AUTHOR
The
.B exiftime
utility and this man page were written by Eric M. Johnston <[email protected]>.
The time adjustment functionality and documentation were derived from portions
of FreeBSD's date(1) command by Brian Somers <[email protected]>.