=head1 NAME

convdate - Convert to/from S<RFC 5322> dates and seconds since epoch

=head1 SYNOPSIS

B<convdate> [B<-dhl>] [B<-c> | B<-n> | B<-s>] [I<date> ...]

=head1 DESCRIPTION

B<convdate> translates the date/time strings given on the command line,
outputting the results one to a line.  The input can either be a date in
S<RFC 5322> format (accepting the variations on that format that innd(8) is
willing to accept), or the number of seconds since epoch (if B<-c> is
given).  The output is either ctime(3) results, the number of seconds
since epoch, or a Usenet Date: header, depending on the options given.

If I<date> is not given, B<convdate> outputs the current date.

=head1 OPTIONS

=over 4

=item B<-c>

Each argument is taken to be the number of seconds since epoch (a time_t)
rather than a date.

=item B<-d>

Output a valid Usenet Date: header instead of the results of ctime(3) for
each date given on the command line.  This is useful for testing the
algorithm used to generate Date: headers for local posts.  Normally, the
date will be in UTC, but see the B<-l> option.

=item B<-h>

Print usage information and exit.

=item B<-l>

Only makes sense in combination with B<-d>.  If given, Date: headers
generated will use the local time zone instead of UTC.

=item B<-n>

Rather than outputting the results of ctime(3) or a Date: header, output
each date given as the number of seconds since epoch (a time_t).  This
option doesn't make sense in combination with B<-d>.

=item B<-s>

Pass each given date to the S<RFC 5322> date parser and print the results of
ctime(3) (or a Date: header if B<-d> is given).  This is the default
behavior.

=back

=head1 EXAMPLES

Most of these examples are taken, with modifications from the original man
page dating from 1991 and were run in the EST/EDT time zone.

    % convdate '10 Feb 1991 10:00:00 -0500'
    Sun Feb 10 10:00:00 1991

    % convdate '13 Dec 91 12:00 EST' '04 May 1990 0:0:0'
    Fri Dec 13 12:00:00 1991
    Fri May  4 00:00:00 1990

    % convdate -n '10 feb 1991 10:00' '4 May 90 12:00'
    666198000
    641880000

    % convdate -c 666198000
    Sun Feb 10 10:00:00 1991

ctime(3) results are in the local time zone.  Compare to:

    % convdate -dc 666198000
    Sun, 10 Feb 1991 15:00:00 -0000 (UTC)

    % env TZ=PST8PDT convdate -dlc 666198000
    Sun, 10 Feb 1991 07:00:00 -0800 (PST)

    % env TZ=EST5EDT convdate -dlc 666198000
    Sun, 10 Feb 1991 10:00:00 -0500 (EST)

The system library functions generally use the environment variable TZ to
determine (or at least override) the local time zone.

=head1 HISTORY

Written by Rich $alz <rsalz@uunet.uu.net>, rewritten and updated by Russ
Allbery <eagle@eyrie.org> for the B<-d> and B<-l> flags.

$Id: convdate.pod 9971 2015-12-10 20:30:10Z iulius $

=head1 SEE ALSO

active.times(5).

=cut
