-# linux-lib.pl
-# Quota functions for all linux version
+=head1 linux-lib.pl
+
+Quota functions for all linux version. See quota-lib.pl for summary
+documentation for this module.
+
+=cut
# Tell the mount module not to check which filesystems are supported,
# as we don't care for the calls made by this module
# Pass UIDs and GIDs to edquota instead of names
$edquota_use_ids = 1;
-# quotas_init()
+=head2 quotas_init
+
+Returns an error message if some quota commands or functionality is missing
+on this system, undef otherwise.
+
+=cut
sub quotas_init
{
if (&has_command("quotaon") && &has_command("quotaoff")) {
}
}
-# quotas_supported()
-# Returns 1 for user quotas, 2 for group quotas or 3 for both
+=head2 quotas_supported
+
+Checks what quota types this OS supports. Returns 1 for user quotas,
+2 for group quotas or 3 for both.
+
+=cut
sub quotas_supported
{
return 3;
}
-# free_space(filesystem, [blocksize])
-# Returns an array containing btotal, bfree, ftotal, ffree
+=head2 free_space(filesystem, [blocksize])
+
+Finds the amount of free disk space on some system. Returns an array
+containing : blocks-total, blocks-free, files-total, files-free
+
+=cut
sub free_space
{
local(@out, @rv);
return @rv;
}
-# quota_can(&mnttab, &fstab)
-# Can this filesystem type support quotas?
-# 0 = No quota support (or not turned on in /etc/fstab)
-# 1 = User quotas only
-# 2 = Group quotas only
-# 3 = User and group quotas
+=head2 quota_can(&mnttab, &fstab)
+
+Can this filesystem type support quotas? Takes array refs from mounted and
+mountable filesystems, and returns one of the following :
+0 = No quota support (or not turned on in /etc/fstab)
+1 = User quotas only
+2 = Group quotas only
+3 = User and group quotas
+
+=cut
sub quota_can
{
return ($_[1]->[3] =~ /usrquota|usrjquota/ ||
$_[0]->[3] =~ /grpquota|grpjquota/ ? 2 : 0);
}
-# quota_now(&mnttab, &fstab)
-# Are quotas currently active?
-# 0 = Not active
-# 1 = User quotas active
-# 2 = Group quotas active
-# 3 = Both active
-# Adding 4 means they cannot be turned off (such as for XFS)
+=head2 quota_now(&mnttab, &fstab)
+
+Are quotas currently active? Takes array refs from mounted and mountable
+filesystems, and returns one of the following :
+0 = Not active
+1 = User quotas active
+2 = Group quotas active
+3 = Both active
+Adding 4 means they cannot be turned off (such as for XFS)
+
+=cut
sub quota_now
{
local $rv = 0;
return $rv;
}
-# supports_status(dir, mode)
+=head2 supports_status(dir, mode)
+
+Internal function to check if the quotaon -p flag is supported.
+
+=cut
sub supports_status
{
if (!defined($supports_status_cache{$_[0],$_[1]})) {
return $supports_status_cache{$_[0],$_[1]};
}
-# quotaon(filesystem, mode)
-# Activate quotas and create quota files for some filesystem. The mode can
-# be 1 for user only, 2 for group only or 3 for user and group
+=head2 quotaon(filesystem, mode)
+
+Activate quotas and create quota files for some filesystem. The mode can
+be one of :
+1 - User only
+2 - Group only
+3 - User and group
+
+=cut
sub quotaon
{
local($out, $qf, @qfile, $flags, $version);
return undef;
}
-# run_quotacheck(filesys, args)
+=head2 run_quotacheck(filesys, args)
+
+Runs the quotacheck command on some filesytem, and returns 1 on success or
+0 on failure.
+
+=cut
sub run_quotacheck
{
-local $out =&backquote_logged("$config{'quotacheck_command'} $_[1] $_[0] 2>&1");
+local $out =&backquote_logged(
+ "$config{'quotacheck_command'} $_[1] $_[0] 2>&1");
return $? || $out =~ /cannot remount|please stop/i ? 0 : 1;
}
-# quotaoff(filesystem, mode)
-# Turn off quotas for some filesystem
+=head2 quotaoff(filesystem, mode)
+
+Turn off quotas for some filesystem. Mode must be 0 for users only, 1 for
+groups only, or 2 for both.
+
+=cut
sub quotaoff
{
return if (&is_readonly_mode());
return undef;
}
-# user_filesystems(user)
-# Fills the array %filesys with details of all filesystem some user has
-# quotas on
+=head2 user_filesystems(user)
+
+Fills the global hash %filesys with details of all filesystem some user has
+quotas on, and returns a count of the number of filesystems.
+XXX
+
+=cut
sub user_filesystems
{
return &parse_quota_output("$config{'user_quota_command'} ".quotemeta($_[0]));
}
-# group_filesystems(user)
-# Fills the array %filesys with details of all filesystem some group has
-# quotas on
+=head2 group_filesystems(user)
+
+Fills the array %filesys with details of all filesystem some group has
+quotas on
+
+=cut
sub group_filesystems
{
return &parse_quota_output("$config{'group_quota_command'} ".quotemeta($_[0]));
return $n;
}
-# filesystem_users(filesystem)
-# Fills the array %user with information about all users with quotas
-# on this filesystem. This may not be all users on the system..
+=head2 filesystem_users(filesystem)
+
+Fills the array %user with information about all users with quotas
+on this filesystem. This may not be all users on the system..
+
+=cut
sub filesystem_users
{
return &parse_repquota_output(
return $nn;
}
-# edit_quota_file(data, filesys, sblocks, hblocks, sfiles, hfiles)
+=head2 edit_quota_file(data, filesys, sblocks, hblocks, sfiles, hfiles)
+
+MISSING DOCUMENTATION
+
+=cut
sub edit_quota_file
{
local($rv, $line, %mtab, @m, @line);
return $rv;
}
-# quotacheck(filesystem, mode(1=users, 2=group))
-# Runs quotacheck on some filesystem
+=head2 quotacheck(filesystem, mode(1=users, 2=group))
+
+Runs quotacheck on some filesystem
+
+=cut
sub quotacheck
{
local $out;
return undef;
}
-# copy_user_quota(user, [user]+)
-# Copy the quotas for some user to many others
+=head2 copy_user_quota(user, [user]+)
+
+Copy the quotas for some user to many others
+
+=cut
sub copy_user_quota
{
for($i=1; $i<@_; $i++) {
return undef;
}
-# copy_group_quota(group, [group]+)
-# Copy the quotas for some group to many others
+=head2 copy_group_quota(group, [group]+)
+
+Copy the quotas for some group to many others
+
+=cut
sub copy_group_quota
{
for($i=1; $i<@_; $i++) {
return undef;
}
-# get_user_grace(filesystem)
-# Returns an array containing btime, bunits, ftime, funits
-# The units can be 0=sec, 1=min, 2=hour, 3=day
+=head2 get_user_grace(filesystem)
+
+Returns an array containing btime, bunits, ftime, funits
+The units can be 0=sec, 1=min, 2=hour, 3=day
+
+=cut
sub get_user_grace
{
return &parse_grace_output($config{'user_grace_command'}, $_[0]);
}
-# get_group_grace(filesystem)
-# Returns an array containing btime, bunits, ftime, funits
-# The units can be 0=sec, 1=min, 2=hour, 3=day
+=head2 get_group_grace(filesystem)
+
+Returns an array containing btime, bunits, ftime, funits
+The units can be 0=sec, 1=min, 2=hour, 3=day
+
+=cut
sub get_group_grace
{
return &parse_grace_output($config{'group_grace_command'}, $_[0]);
}
-# default_grace()
-# Returns 0 if grace time can be 0, 1 if zero grace means default
+=head2 default_grace
+
+Returns 0 if grace time can be 0, 1 if zero grace means default
+
+=cut
sub default_grace
{
return 0;
return @rv;
}
-# edit_grace_file(data, filesystem, btime, bunits, ftime, funits)
+=head2 edit_grace_file(data, filesystem, btime, bunits, ftime, funits)
+
+MISSING DOCUMENTATION
+
+=cut
sub edit_grace_file
{
local($rv, $line, @m, %mtab, @line);
return $rv;
}
-# grace_units()
-# Returns an array of possible units for grace periods
+=head2 grace_units
+
+Returns an array of possible units for grace periods
+
+=cut
sub grace_units
{
return ($text{'grace_seconds'}, $text{'grace_minutes'}, $text{'grace_hours'},
$text{'grace_days'});
}
-# fs_block_size(dir, device, filesystem)
-# Returns the size of blocks on some filesystem, or undef if unknown.
-# Consult the dumpe2fs command where possible.
+=head2 fs_block_size(dir, device, filesystem)
+
+Returns the size of blocks on some filesystem, or undef if unknown.
+Consult the dumpe2fs command where possible.
+
+=cut
sub fs_block_size
{
if ($_[2] eq "ext2" || $_[2] eq "ext3") {
$unit_to_name{$name_to_unit{$k}} = $k;
}
-# Returns a hash mapping mount points to devices
+=head2 get_mtab_map
+
+Returns a hash mapping mount points to devices
+
+=cut
sub get_mtab_map
{
local $mm = $module_info{'usermin'} ? "usermount" : "mount";
-# quota-lib.pl
-# Common functions for quota management.
+=head1 quota-lib.pl
+
+Functions for Unix user and group quota management. Some of the functionality
+is implemented in OS-specific library files which get automatically included
+into this one, like linux-lib.pl. Check the documentation on that file for
+more functions.
+
+Example code:
+
+ foreign_require('quota', 'quota-lib.pl');
+ XXX
+
+=cut
do '../web-lib.pl';
&init_config();
$email_cmd = "$module_config_directory/email.pl";
-# list_filesystems()
-# Returns a list of details of local filesystems on which quotas are supported
-# directory device type options quotacan quotanow
+=head2 list_filesystems
+
+Returns a list of details of local filesystems on which quotas are supported.
+Each is an array ref whose values are :
+directory - Mount point, like /home
+device - Source device, like /dev/hda1
+type - Filesystem type, like ext3
+options - Mount options, like rw,usrquota,grpquota
+quotacan - Can this filesystem type support quotas?
+quotanow - Are quotas enabled right now?
+
+The values of quotacan and quotanow are :
+0 - No quotas
+1 - User quotas only
+2 - Group quotas only
+3 - User and group quotas
+
+=cut
sub list_filesystems
{
local $f;
return grep { $_->[4] } @mtab;
}
-# parse_options(type, options)
-# Convert an options string for some filesystem into the associative
-# array %options
+=head2 parse_options(type, options)
+
+Convert an options string for some filesystem into the global hash %options.
+
+=cut
sub parse_options
{
local($_);
}
}
-# user_quota(user, filesystem)
-# Returns an array of ublocks, sblocks, hblocks, ufiles, sfiles, hfiles
-# for some user, or an empty array if no quota has been assigned
+=head2 user_quota(user, filesystem)
+
+Returns an array of ublocks, sblocks, hblocks, ufiles, sfiles, hfiles
+for some user on some filesystem, or an empty array if no quota has been
+assigned.
+
+=cut
sub user_quota
{
local (%user, $n, $i);
return ();
}
-# group_quota(group, filesystem)
-# Returns an array of ublocks, sblocks, hblocks, ufiles, sfiles, hfiles
-# for some group, or an empty array if no quota has been assigned
+=head2 group_quota(group, filesystem)
+
+Returns an array of ublocks, sblocks, hblocks, ufiles, sfiles, hfiles
+for some group on some filesystem, or an empty array if no quota has been
+assigned.
+
+=cut
sub group_quota
{
local (%group, $n, $i);
return ();
}
-# edit_user_quota(user, filesys, sblocks, hblocks, sfiles, hfiles)
-# Sets the disk quota for some user
+=head2 edit_user_quota(user, filesys, sblocks, hblocks, sfiles, hfiles)
+
+Sets the disk quota for some user. The parameters are :
+user - Unix username
+filesys - Filesystem on which to change quotas
+sblocks - Soft block limit
+hblocks - Hard block limit
+sfiles - Sort files limit
+hfiles - Hard files limit
+
+=cut
sub edit_user_quota
{
if ($config{'user_setquota_command'} &&
}
}
-# edit_group_quota(group, filesys, sblocks, hblocks, sfiles, hfiles)
-# Sets the disk quota for some group
+=head2 edit_group_quota(group, filesys, sblocks, hblocks, sfiles, hfiles)
+
+Sets the disk quota for some group The parameters are :
+user - Unix group name
+filesys - Filesystem on which to change quotas
+sblocks - Soft block limit
+hblocks - Hard block limit
+sfiles - Sort files limit
+hfiles - Hard files limit
+
+=cut
sub edit_group_quota
{
if ($config{'group_setquota_command'} &&
}
}
-# edit_user_grace(filesystem, btime, bunits, ftime, funits)
-# Change the grace times for blocks and files on some filesystem
+=head2 edit_user_grace(filesystem, btime, bunits, ftime, funits)
+
+Change the grace times for blocks and files on some filesystem. Parameters are:
+filesystem - Filesystem to change the grace time on
+btime - Number of units after which a user over his soft block limit is turned
+ into a hard limit.
+bunits - Units for the block grace time, such as 'seconds', 'minutes',
+ 'hours' or 'days'
+ftime - Number of units after which a user over his soft file limit is turned
+ into a hard limit.
+funits - Units for the file grace time, such as 'seconds', 'minutes',
+ 'hours' or 'days'
+
+=cut
sub edit_user_grace
{
$ENV{'EDITOR'} = $ENV{'VISUAL'} = "$module_root_directory/edgrace.pl";
&system_logged($config{'user_grace_command'});
}
-# edit_group_grace(filesystem, btime, bunits, ftime, funits)
-# Change the grace times for blocks and files on some filesystem
+=head2 edit_group_grace(filesystem, btime, bunits, ftime, funits)
+
+Change the grace times for groups for blocks and files on some filesystem.
+The parameters are the same as edit_user_grace.
+
+=cut
sub edit_group_grace
{
$ENV{'EDITOR'} = $ENV{'VISUAL'} = "$module_root_directory/edgrace.pl";
&system_logged($config{'group_grace_command'});
}
-# quota_input(name, value, [blocksize])
-# Prints an input for selecting a quota or unlimited, in a table
+=head2 quota_input(name, value, [blocksize])
+
+Returns an input for selecting a quota or unlimited, in a table. For internal
+use mainly.
+
+=cut
sub quota_input
{
return &ui_radio($_[0]."_def", $_[1] == 0 ? 1 : 0,
"a_inputbox(@_);
}
-# quota_inputbox(name, value, [blocksize])
-# Returns an input for selecting a quota
+=head2 quota_inputbox(name, value, [blocksize])
+
+Returns an input for selecting a quota. Mainly for internal use.
+
+=cut
sub quota_inputbox
{
if ($_[2]) {
}
}
-# quota_parse(name, [bsize], [nodef])
+=head2 quota_parse(name, [bsize], [nodef])
+
+Parses inputs from the form generated by quota_input.
+
+=cut
sub quota_parse
{
if ($in{$_[0]."_def"} && !$_[2]) {
}
}
-# can_edit_filesys(filesys)
+=head2 can_edit_filesys(filesys)
+
+Returns 1 if the current Webmin user can manage quotas on some filesystem.
+
+=cut
sub can_edit_filesys
{
local $fs;
return 0;
}
-# can_edit_user(user)
+=head2 can_edit_user(user)
+
+Returns 1 if the current Webmin user can manage quotas for some Unix user.
+
+=cut
sub can_edit_user
{
if ($access{'umode'} == 0) {
}
}
-# can_edit_group(group)
+=head2 can_edit_group(group)
+
+Returns 1 if the current Webmin user can manage quotas for some Unix group.
+
+=cut
sub can_edit_group
{
return 1 if ($access{'gmode'} == 0);
$access{'gmode'} == 2 && !$gcan{$_[0]};
}
-# filesystem_info(filesystem, &hash, count, [blocksize])
+=head2 filesystem_info(filesystem, &hash, count, [blocksize])
+
+Returns two strings containing information about the amount of disk space
+granted and used on some filesystem. For internal use.
+
+=cut
sub filesystem_info
{
local @fs = &free_space($_[0], $_[3]);
}
}
-# block_size(dir, [for-filesys])
-# Returns the size (in bytes) of blocks on some filesystem
+=head2 block_size(dir, [for-filesys])
+
+Returns the size (in bytes) of blocks on some filesystem, if known. All
+quota functions deal with blocks, so they must be multipled by the value
+returned by this function before display to users.
+
+=cut
sub block_size
{
return undef if (!$config{'block_mode'});
return undef;
}
-# nice_limit(amount, bsize, no-blocks)
+=head2 nice_limit(amount, bsize, no-blocks)
+
+Internal function to show a quota limit nicely formatted.
+
+=cut
sub nice_limit
{
local ($amount, $bsize, $noblocks) = @_;
$bsize && !$noblocks ? &nice_size($amount*$bsize) : $amount;
}
-sub print_grace
-{
-print "<td>",($_[0] || "<br>"),"</td>\n";
-}
+=head2 find_email_job
+Returns the cron job hash ref for the quota limit monitoring email job.
+
+=cut
sub find_email_job
{
&foreign_require("cron", "cron-lib.pl");
return $job;
}
-# create_email_job()
-# Creates the cron job for scheduled emailing
+=head2 create_email_job
+
+Creates the cron job for scheduled emailing, which runs every 10 minutes.
+
+=cut
sub create_email_job
{
&foreign_require("cron", "cron-lib.pl");
}
}
-# trunc_space(string)
-# Removes spaces from the start and end of a string
+=head2 trunc_space(string)
+
+Removes spaces from the start and end of a string.
+
+=cut
sub trunc_space
{
local $rv = $_[0];
return $rv;
}
-# to_percent(used, total)
+=head2 to_percent(used, total)
+
+Converts an amount used and a total into a percentage.
+
+=cut
sub to_percent
{
if ($_[1]) {
}
}
-# select_grace_units(name, value)
-# Returns a menu for selecting grace time units
+=head2 select_grace_units(name, value)
+
+Returns a menu for selecting grace time units.
+
+=cut
sub select_grace_units
{
local @uarr = &grace_units();