SAMPLE

NAME

SYNOPSIS

DESCRIPTION

sample and its associated tools are intended to monitor ("sample") outdated/oversized files and handle them in a user-defined fashion. this can involve deleting, moving, or updating with new content among other things.

the sample program is a simple console-based interface used to make and validate ~/.sample files, similar to the respective use of the crontab program. however, the sample program is not required in any way to make your ~/.sample file, it can be created/modified completely manually.

if no command-line arguments are specified for sample it will attempt to edit the current user's ~/.sample file.  

OPTIONS

-v

shows the version information of sample

-n

if sample is making a new ~/.sample file, it will not include the "help" configuration comments

-r

removes a user's ~/.sample file (this can be used in conjunction with the -u option)

-l

(root-only) lists all potentially processable ~/.sample and spooled sample (~/.sample_spool/*) files. this is for admin maintenance/monitoring purposes (does not list /etc/sampletab/* files as they are already consolidated)

-t

(root-only) switch to editing a user's "/etc/sampletab/username", instead of "/home/username/.sample" (this can be used in conjunction with the -u option, this feature is explained in the TABS section)

-u user

(root-only) modify a specified user's ~/.sample file, instead of their own

-e editor

specify an alternate editor to edit your ~/.sample file

FORMAT

[TYPE]          [TIME|SIZE]             [PATH]          [EXEC]

each value being separated by TABS (\t). the literal form of this is:

"if TYPE has past TIME for a file contained in PATH then run EXEC"

OR, for filesize comparisons:

"if TYPE is smaller/larger than SIZE for a file contained in PATH then run EXEC"

description of each field:

field [TYPE]:

value must be set to one of the following:

A      compare TIME to the last access of a file         (older than)
a      compare TIME to the last access of a file         (newer than)
C      compare TIME to the last status change of file    (older than)
c      compare TIME to the last status change of file    (newer than)
M      compare TIME to the last modification of file     (older than)
m      compare TIME to the last modification of file     (newer than)
S      compare SIZE to the size of file                  (greater than)
s      compare SIZE to the size of file                  (less than)

the lowercase versions of the above are lowercase because they are deemed less commonly used than the uppercase versions.

field [TIME]:

for types A, a, C, c, M and m. the value must be set to one or a combination of the following:

s      seconds (ex. "60s")
m      minutes (ex. "60m")
h      hours   (ex. "24h")
d      days    (ex. "7d")
w      weeks   (ex. "52w")
M      months  (ex. "12M")
Y      years   (ex. "1Y")

there should be no spaces in this field, for example "1h30m" would be the equivalent of matching a 90-minute or older file(s).

field [SIZE]:

for types S and s. the value must be set to one or a combination of the following:

B      bytes          (ex. "1024B")
K      kilobytes      (ex. "1024K")
M      megabytes      (ex. "1024M")
G      gigabytes      (ex. "1G")

there should be no spaces in this field, for example "1M512K" would be the equivalent of matching a 1.5 meg file(s).

field [PATH]:

the PATH field can be separated by colons (:) to include multiple paths to check for outdated/oversized files. this format follows the wildcard method supported by most shells, for example "~/*.txt:~/*.rtf" would attempt to find all outdated/oversized .txt and .rtf files in your home directory.

field [EXEC]:

this is executed if sampled finds an outdated/oversized file is found in PATH, the following variables will be filled in with their corresponding value:

%%     inserts a literal %
%s     exact path to the file matched          (shell-escaped)
%S     exact path to the file matched          (NON-escaped)
%f     only the filename of the matched path   (shell-escaped)
%F     only the filename of the matched path   (NON-escaped)
%p     only the path of the matched path       (shell-escaped)
%P     only the path of the matched path       (NON-escaped)
%l     symbolic link path, becomes %s if none  (shell-escaped)
%L     symbolic link path, becomes %S if none  (NON-escaped)
%u     file owner's user id
%U     file owner's user name
%g     file owner's group id
%G     file owner's group name
%m     (octal) file mode                       (ex. "0777")
%M     (string) file mode                      (ex. "-rwxrwxrwx")
%n     size of the file in bytes
%i     inode of file
%0-9   sub-directory hierarchy variables

TABS

EXAMPLE

an example ~/.sample might look like:

# Set your desired shell. (may be restricted in some
# configurations)
SHELL=/bin/sh

# Move old file(s) in the home directory to a sub-folder if
# they haven't been accessed/read in over 6 months.
A      6M             ~                       mv -f -- %s ~/old/%f

# Remove (1.5 year old) unread inactive user's mail.
A      1Y6M           /var/mail/              rm -f -- %s

# Remove files in /tmp/* and /var/tmp/* after 1 week of no
# modifications.
M      1w             /tmp:/var/tmp           rm -f -- %s

# Update/regenerate a static (rss) webpage every 90 minutes.
# ("90m" also works)
M      1h30m          ~/www/site.rss          perl ~/make_rss.pl > %s

# This would essentially make a drop folder/directory in /drop/,
# which would simply process and delete any file placed in
# the directory. (sampled, by default, runs on the minute.
# meaning this would not actually process every second)
M      1s             /drop/                  ~/proc.sh %s ; rm -f -- %s

# This would delete 100 meg or larger files in your home
# directory.
S      100M           ~                       rm -f -- %s

# (root) Log rotation, make sure it's bash for this. this will
# rotate *.log files in /var/log when they grow over 10MB.
SHELL=/bin/bash
S      10M            /var/log/*.log          for ((i=5;i>=0;i--)); do mv -f %s.$i %s.$[i+1]; done; mv -f %s %s.0; touch %s

ENVIRONMENT

sample interface variables:

EDITOR

used to determine the text editor to edit the ~/.sample file

PATH

used to determine the path of the text editor

FILES

AUTHOR

BUGS

COPYRIGHT

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

FORMAT

TABS

EXAMPLE

ENVIRONMENT

FILES

AUTHOR

BUGS

COPYRIGHT

SEE ALSO