Section: Sample (1)
Updated: August 2007
Index Return to Main Contents


sample - interface to edit ~/.sample files  


sample [-vnrlt] [-u user] [-e editor]  


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.  


shows the version information of sample
if sample is making a new ~/.sample file, it will not include the "help" configuration comments
removes a user's ~/.sample file (this can be used in conjunction with the -u option)
(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)
(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


the format of your ~/.sample file via the sample interface or by directly editing the file is a job-per-line format, similar to that of cron. the format is:

[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



sample tabs, found in /etc/sampletab/ by default, are sample files in exactly the same format as ~/.sample files except they are designed to be static and only editable by root.

in general terms; "/etc/sampletab/username" is the same as "/home/username/.sample", except the user cannot edit the sampletab version.

root can edit these files by appending the -t argument to the sample command.



an example ~/.sample might look like:

# Set your desired shell. (may be restricted in some
# configurations)

# 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 ~/ > %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/                  ~/ %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.
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



environmental variables can be set by placing VAR=VALUE on a blank line in your ~/.sample file.

sample interface variables:

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

used to determine the path of the text editor




Written by v9/fakehalo. []  


Report bugs to <>.  


Copyright © 2007 fakehalo.
This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  


samples(1) sample.conf(5) sampled(8) samputil(8)




This document was created by man2html, using the manual pages.