diff --git a/web-lib-funcs.pl b/web-lib-funcs.pl index 20935a662..f58fa42ca 100755 --- a/web-lib-funcs.pl +++ b/web-lib-funcs.pl @@ -2,8 +2,14 @@ Common functions for Webmin CGI scripts. This file gets in-directly included by all scripts that use web-lib.pl. +Example code: -XXX example code + require '../web-lib.pl'; + init_config(); + require '../ui-lib.pl'; + ui_print_header(undef, 'My Module', ''); + print 'This is Webmin version ',get_webmin_version(),'

\n'; + ui_print_footer(); =cut @@ -4218,7 +4224,9 @@ if ($gconfig{'logclear'}) { $write_logtime = 1; } } - else { $write_logtime = 1; } + else { + $write_logtime = 1; + } if ($write_logtime) { open(LOGTIME, ">$webmin_logfile.time"); print LOGTIME time(),"\n"; @@ -6842,8 +6850,16 @@ return @_ > 1 ? $_[1] : "application/octet-stream"; =head2 open_tempfile([handle], file, [no-error], [no-tempfile], [safe?]) -Returns a temporary file for writing to some actual file. -XXX +Opens a file handle for writing to a temporary file, which will only be +renamed over the real file when the handle is closed. This allows critical +files like /etc/shadow to be updated safely, even if writing fails part way +through due to lack of disk space. +The parameters are : +handle - File handle to open, as you would use in Perl's open function. +file - Full path to the file to write, prefixed by > or >> to indicate over-writing or appending. In append mode, no temp file is used. +no-error - By default, this function will call error if the open fails. Setting this parameter to 1 causes it to return 0 on failure, and set $! with the error code. +no-tempfile - If set to 1, writing will be direct to the file instead of using a temporary file. +safe - Indicates to users in read-only mode that this write is safe and non-destructive. =cut sub open_tempfile @@ -6966,7 +6982,7 @@ else { =head2 close_tempfile(file|handle) Copies a temp file to the actual file, assuming that all writes were -successful. +successful. The handle must have been one passed to open_tempfile. =cut sub close_tempfile @@ -7011,9 +7027,21 @@ else { } } +=head2 print_tempfile(handle, text, ...) + +Like the normal print function, but calls &error on failure + +=cut +sub print_tempfile +{ +local ($fh, @args) = @_; +(print $fh @args) || &error(&text("efilewrite", + $main::open_temphandles{$fh} || $fh, $!)); +} + =head2 is_selinux_enabled -Returns 1 if SElinux is supported on this system and enabled +Returns 1 if SElinux is supported on this system and enabled, 0 if not. =cut sub is_selinux_enabled @@ -7043,7 +7071,8 @@ return $main::selinux_enabled_cache; =head2 get_clear_file_attributes(file) Finds file attributes that may prevent writing, clears them and returns them -as a list. May call error. +as a list. May call error. Mainly for internal use by open_tempfile and +close_tempfile. =cut sub get_clear_file_attributes @@ -7072,7 +7101,8 @@ return @old_attributes; =head2 reset_file_attributes(file, &attributes) -Put back cleared attributes on some file. May call error. +Put back cleared attributes on some file. May call error. Mainly for internal +use by close_tempfile. =cut sub reset_file_attributes @@ -7088,21 +7118,10 @@ if (&indexof("i", @$old_attributes) >= 0) { } } -=head2 print_tempfile(handle, text, ...) - -Like the normal print function, but calls &error on failure - -=cut -sub print_tempfile -{ -local ($fh, @args) = @_; -(print $fh @args) || &error(&text("efilewrite", - $main::open_temphandles{$fh} || $fh, $!)); -} - =head2 cleanup_tempnames -Remove all temporary files +Remove all temporary files generated using transname. Typically only called +internally when a Webmin script exits. =cut sub cleanup_tempnames @@ -7116,7 +7135,9 @@ foreach $t (@main::temporary_files) { =head2 open_lock_tempfile([handle], file, [no-error]) -Returns a temporary file for writing to some actual file, and also locks it +Returns a temporary file for writing to some actual file, and also locks it. +Effectively the same as calling lock_file and open_tempfile on the same file, +but calls the unlock for you automatically when it is closed. =cut sub open_lock_tempfile @@ -7153,7 +7174,7 @@ if ($$ == $main::initial_process_id) { =head2 month_to_number(month) -Converts a month name like feb to a number like 1 +Converts a month name like feb to a number like 1. =cut sub month_to_number @@ -7163,7 +7184,7 @@ return $month_to_number_map{lc(substr($_[0], 0, 3))}; =head2 number_to_month(number) -Converts a number like 1 to a month name like Feb +Converts a number like 1 to a month name like Feb. =cut sub number_to_month @@ -7244,7 +7265,7 @@ return !$foundany ? undef : defined(%rv) ? \%rv : undef; =head2 supports_rbac([module]) -Returns 1 if RBAC client support is available +Returns 1 if RBAC client support is available, such as on Solaris. =cut sub supports_rbac @@ -7258,8 +7279,11 @@ if ($_[0]) { return 1; } -# use_rbac_module_acl(user, module) -# Returns 1 if some user should use RBAC to get permissions for a module +=head2 use_rbac_module_acl(user, module) + +Returns 1 if some user should use RBAC to get permissions for a module + +=cut sub use_rbac_module_acl(user, module) { local $u = defined($_[0]) ? $_[0] : $base_remote_user; @@ -7272,7 +7296,13 @@ return $access{'rbac'} ? 1 : 0; =head2 execute_command(command, stdin, stdout, stderr, translate-files?, safe?) Runs some command, possibly feeding it input and capturing output to the -give files or scalar references. +give files or scalar references. The parameters are : +command - Full command to run, possibly including shell meta-characters. +stdin - File to read input from, or a scalar ref containing input, or undef if no input should be given. +stdout - File to write output to, or a scalar ref into which output should be placed, or undef if the output is to be discarded. +stderr - File to write error output to, or a scalar ref into which error output should be placed, or undef if the error output is to be discarded. +translate-files - Set to 1 to apply filename translation to any filenames. Usually has no effect. +safe - Set to 1 if this command is safe and does not modify the state of the system. =cut sub execute_command @@ -7381,7 +7411,8 @@ return $?; =head2 open_readfile(handle, file) -Opens some file for reading. Returns 1 on success, 0 on failure +Opens some file for reading. Returns 1 on success, 0 on failure. Pretty much +exactly the same as Perl's open function. =cut sub open_readfile @@ -7394,8 +7425,9 @@ return open($fh, "<".$realfile); =head2 open_execute_command(handle, command, output?, safe?) -Runs some command, with the specified filename set to either write to it if -in-or-out is set to 0, or read to it if output is set to 1. +Runs some command, with the specified file handle set to either write to it if +in-or-out is set to 0, or read to it if output is set to 1. The safe flag +indicates if the command modifies the state of the system or not. =cut sub open_execute_command @@ -7429,7 +7461,8 @@ elsif ($mode == 2) { =head2 translate_filename(filename) -Applies all relevant registered translation functions to a filename +Applies all relevant registered translation functions to a filename. Mostly +for internal use, and typically does nothing. =cut sub translate_filename @@ -7447,7 +7480,8 @@ return $realfile; =head2 translate_command(filename) -Applies all relevant registered translation functions to a command +Applies all relevant registered translation functions to a command. Mostly +for internal use, and typically does nothing. =cut sub translate_command @@ -7467,7 +7501,8 @@ return $realcmd; Registers some function to be called when the specified module (or all modules) tries to open a file for reading and writing. The function must -return the actual file to open. +return the actual file to open. This allows you to override which files +other code actually operates on, via the translate_filename function. =cut sub register_filename_callback @@ -7480,7 +7515,8 @@ push(@main::filename_callbacks, [ $mod, $func, $args ]); Registers some function to be called when the specified module (or all modules) tries to execute a command. The function must return the actual -command to run. +command to run. This allows you to override which commands other other code +actually runs, via the translate_command function. =cut sub register_command_callback @@ -7491,7 +7527,9 @@ push(@main::command_callbacks, [ $mod, $func, $args ]); =head2 capture_function_output(&function, arg, ...) -Captures output that some function prints to STDOUT, and returns it +Captures output that some function prints to STDOUT, and returns it. Useful +for functions outside your control that print data when you really want to +manipulate it before output. =cut sub capture_function_output @@ -7513,7 +7551,10 @@ return wantarray ? ($out, \@rv) : $out; =head2 modules_chooser_button(field, multiple, [form]) -Returns HTML for a button for selecting one or many Webmin modules +Returns HTML for a button for selecting one or many Webmin modules. +field - Name of the HTML field to place the module names into. +multiple - Set to 1 if multiple modules can be selected. +form - Index of the form on the page. =cut sub modules_chooser_button @@ -7535,7 +7576,9 @@ return "