NAME

ActiveState::Unix::Crontab - Portable manipulation of the crontab system

SYNOPSIS

 use ActiveState::Unix::Crontab qw(cron_add);
 
 cron_add(cmd => "ls -l /etc");

DESCRIPTION

This module provides function that allow portable manipulation of the crontab system found on Unix.

The following functions are provided and manipulate the crontab entry for the current user

cron_edit()

This function invokes the editor on the current crontab file. The function will croak on failure.

cron_add( $line )
cron_add( %opts )

This function add an entry to the current crontab file. The function either takes a single cron line or a set of key/value paired parameters; see cron_parse() description below. A comment can be passed together with a cmd.

$line = cron_format( %opts )

This formats a single crontab entry line. This is the inverse of the cron_parse() function. See the description of cron_parse() for what options to pass.

%opts = cron_parse( $line )

This taks a single crontab line and parse it out as a set of key/value pairs. This is the inverse of the cron_format() function. The cron_list() function is used to read out lines from crontab.

There are 4 different results that can be returned:

  1. An empty line simply returns an empty %opts.

  2. An line containing the setting of an environment variable returns:

      env:     name of the environment variable
      value:   the value it takes
  3. An line containing a scheduled command contains:

      cmd:     what command to execute
      data:    stdin data provided to the command
      enabled: is the command enabled or not
      min:     which minute to run
      hour:    which hour to run
      mday:    which day of month to run
      mon:     which month to run
      wday:    which week day to run

    Only cmd will always be there. The cmd and data is plain strings. The enabled is a boolean. The time and date fields take a list of numbers or ranges:

      5
      1,2
      1-3
      1,2,5-9,12

    Note that no space is allowed in these values. The range for wday is 0 .. 6, with 0 as Sunday.

    Portable applications should limit the settings to this format. Some implementations of cron also allow step values and/or plain English names for the weekdays or months.

  4. Anything else is returned as a comment:

      comment: comment text (including leading '#')
cron_install( @lines )

This installes the given crontab lines as the current crontab file.

@lines = cron_list()

This extract the crontab lines from the current crontab file. The lines are returned as is and can be parsed with the cron_parse() function.

@cmds = cron_cmds()

This extracts the currently installed crontab commands.

The following commands are available for 'root' to use:

cron_allow_user( $user )

This make sure that the given user is allowed to use the crontab system.

cron_deny_user( $user )

The tell the system the the given user is to allowed to use the crontab system.

cron_remove_user( $user )

This remove all records of the given user in the crontab system.

EXAMPLE

This disables all cron commands:

 #!/usr/bin/perl -w
 use ActiveState::Unix::Crontab qw(cron_list cron_install
                                   cron_parse cron_format);
 
 my $mod;
 my @list = cron_list();
 
 for (@list) {
     my %line = cron_parse($_);
     if ($line{cmd} && $line{enabled}) {
         $line{enabled} = 0;
         $_ = cron_format(%line);
         $mod++;
     }
 }
 
 cron_install(@list);

Enabling them again is left as an exercise for the interested developer.

cron_install(@list) if $mod;

SEE ALSO

crontab