Localtime - How to Tell the Current Time in Perl

Using Localtime to Find the Time in Your Perl Scripts

Cuckoo clocks with different time zones
STOCK4B / Getty Images

Perl has a handy built-in function for finding the current date and time in your scripts. However, when we talk about finding the time, we're talking about the time that is currently set on the machine that's running the script. For instance, if you're running your Perl script on your local machine, localtime will return the current time you have set, and presumably set to your current timezone.

When you run the same script on a web server, you may find that ​localtime there is off from ​localtime on your desktop system. The server might be in a different time zone, or be set incorrectly. Each machine may have a totally different idea of what localtime is and it may take some adjusting, either within the script or on the server itself, to get it to match up to what you're expecting.

The localtime function returns a list full of data about the current time, some of which will need to be adjusted. Run the program below and you'll see each element in the list printed on the line and separated by spaces.

@timeData = localtime(time);
print join(' ', @timeData);

You should see something similar to this, although the number could be very different.

20 36 8 27 11 105 2 360 0

These elements of the current time are, in order:

  • Seconds past the minute
  • Minutes past the hour
  • Hours past midnight
  • Day of the month
  • Months past the start of the year
  • Number of years since 1900
  • Number of days since the start of the week (Sunday)
  • Number of days since the start of the year
  • Whether or not daylight savings is active

So if we return to the example and attempt to read it, you'll see that it's 8:36:20 AM on December the 27th, 2005, it's 2 days past Sunday (Tuesday), and it's 360 days since the start of the year. Daylight savings time is not active.

Making the Perl Localtime Readable

A few of the elements in the array that localtime returns are a bit awkward to read. Who would think of the current year in terms of the number of years past 1900? Let's take a look at an example that makes our date and time clearer.

@months = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
@weekDays = qw(Sun Mon Tue Wed Thu Fri Sat Sun);
($second, $minute, $hour, $dayOfMonth, $month, $yearOffset, $dayOfWeek, $dayOfYear, $daylightSavings) = localtime();
$year = 1900 + $yearOffset;
$theTime = "$hour:$minute:$second, $weekDays[$dayOfWeek] $months[$month] $dayOfMonth, $year";
print $theTime; 

When you run the program, you should see a much more readable date and time like this:

 9:14:42, Wed Dec 28, 2005 

So what did we do to create this more readable version? First we prepare two arrays with the names of the months and days of the week.

 @months = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
@weekDays = qw(Sun Mon Tue Wed Thu Fri Sat Sun); 

Since the localtime function returns these elements in values ranging from 0-11 and 0-6 respectively, they are perfect candidates for an array. The value returned by localtime can be used as a numeric address to access the correct element in the array.

 $months[$month] $weekDays[$dayOfWeek]

The next step is to get all the values from the localtime function. In this example, we're using a Perl shortcut to automatically place each element in the localtime array into its own variable. We've chosen names so that it's easy to remember which element is which.

 ($second, $minute, $hour, $dayOfMonth, $month, $yearOffset, $dayOfWeek, $dayOfYear, $daylightSavings) = localtime();

We also need to adjust the value of the year. Remember that localtime returns the number of years since 1900, so in order to find the current year, we'll need to add 1900 to the value we're given.

 $year = 1900 + $yearOffset;

How to Tell the Current GM Time in Perl

Let's say that you want to avoid all possible time zone confusions and take control of the offset yourself. Getting the current time in localtime will always return a value that is based on the machine's timezone settings - a server in the US will return one time, while a server in Australia will return one nearly a full day different due to the time zone differences.

Perl has a second handy time-telling function that works in exactly the same way as localtime, but instead of returning the time fixed for your machine's time zone, it returns Coordinated Universal Time (abbreviated as UTC, also called Greenwich Mean Time or GMT). Simply enough the function is called gmtime

@timeData = gmtime(time);
print join(' ', @timeData); 

Other than the fact the time returned will be the same on every machine and in GMT, there is no difference between the gmtime and localtime functions. All the data and conversions are done in the same way.

@months = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
@weekDays = qw(Sun Mon Tue Wed Thu Fri Sat Sun);
($second, $minute, $hour, $dayOfMonth, $month, $yearOffset, $dayOfWeek, $dayOfYear, $daylightSavings) = gmtime();
$year = 1900 + $yearOffset;
$theGMTime = "$hour:$minute:$second, $weekDays[$dayOfWeek] $months[$month] $dayOfMonth, $year";
print $theGMTime; 
  1. localtime will return the current local time on the machine that runs the script.
  2. gmtime will return the universal Greenwich Mean Time, or GMT (or UTC).
  3. The return values may not be quite what you expect, so make sure you convert them as necessary.