return $rv;
}
-=head2 read_http_connection(handle, [amount])
+=head2 read_http_connection(&handle, [bytes])
-Reads either one line or up to the specified amount of data from the handle.
-XXX
+Reads either one line or up to the specified number of bytes from the handle,
+originally supplied by make_http_connection.
=cut
sub read_http_connection
return $rv;
}
-=head2 write_http_connection(handle, [data+])
+=head2 write_http_connection(&handle, [data+])
-Writes the given data to the handle
+Writes the given data to the given HTTP connection handle.
=cut
sub write_http_connection
}
}
-=head2 close_http_connection(handle)
+=head2 close_http_connection(&handle)
-MISSING DOCUMENTATION
+Closes a connection to an HTTP server, identified by the given handle.
=cut
sub close_http_connection
=head2 clean_environment
Deletes any environment variables inherited from miniserv so that they
-won't be passed to programs started by webmin.
+won't be passed to programs started by webmin. This is useful when calling
+programs that check for CGI-related environment variables and modify their
+behaviour, and to avoid passing sensitive variables to un-trusted programs.
=cut
sub clean_environment
=head2 reset_environment
-Puts the environment back how it was before &clean_environment
+Puts the environment back how it was before clean_environment was callled.
=cut
sub reset_environment
}
}
-$webmin_feedback_address = "feedback\@webmin.com";
-
=head2 progress_callback
-Never called directly, but useful for passing to &http_download
+Never called directly, but useful for passing to &http_download to print
+out progress of an HTTP request.
=cut
sub progress_callback
Changes the user and group of the current process to that of the unix user
with the same name as the current webmin login, or fails if there is none.
+This should be called by Usermin module scripts that only need to run with
+limited permissions.
=cut
sub switch_to_remote_user
Creates per-user config directories and sets $user_config_directory and
$user_module_config_directory to them. Also reads per-user module configs
-into %userconfig
+into %userconfig. This should be called by Usermin module scripts that need
+to store per-user preferences or other settings.
=cut
sub create_user_config_dirs
=head2 create_missing_homedir(&uinfo)
-If auto homedir creation is enabled, create one for this user if needed
+If auto homedir creation is enabled, create one for this user if needed.
+For internal use only.
=cut
sub create_missing_homedir
=head2 filter_javascript(text)
-Disables all javascript <script>, onClick= and so on tags in the given HTML
+Disables all javascript <script>, onClick= and so on tags in the given HTML,
+and returns the new HTML. Useful for displaying HTML from an un-trusted source.
=cut
sub filter_javascript
=head2 resolve_links(path)
-Given a path that may contain symbolic links, returns the real path
+Given a path that may contain symbolic links, returns the real path.
=cut
sub resolve_links
=head2 simplify_path(path, bogus)
-Given a path, maybe containing stuff like ".." and "." convert it to a
-clean, absolute form. Returns undef if this is not possible
+Given a path, maybe containing elements ".." and "." , convert it to a
+clean, absolute form. Returns undef if this is not possible.
=cut
sub simplify_path
=head2 flush_webmin_caches
-Clears all in-memory and on-disk caches used by webmin
+Clears all in-memory and on-disk caches used by Webmin.
=cut
sub flush_webmin_caches
=head2 list_usermods
Returns a list of additional module restrictions. For internal use in
-usermin only.
+Usermin only.
=cut
sub list_usermods
=head2 available_usermods(&allmods, &usermods)
Returns a list of modules that are available to the given user, based
-on usermod additional/subtractions
+on usermod additional/subtractions. For internal use by Usermin only.
=cut
sub available_usermods
=head2 get_available_module_infos(nocache)
Returns a list of modules available to the current user, based on
-operating system support, access control and usermod restrictions.
+operating system support, access control and usermod restrictions. Useful
+in themes that need to display a list of modules the user can use.
+Each element of the returned array is a hash reference in the same format as
+returned by get_module_info.
=cut
sub get_available_module_infos
=head2 get_visible_module_infos(nocache)
-Like get_available_module_infos, but excludes hidden modules from the list
+Like get_available_module_infos, but excludes hidden modules from the list.
+Each element of the returned array is a hash reference in the same format as
+returned by get_module_info.
=cut
sub get_visible_module_infos
=head2 is_under_directory(directory, file)
Returns 1 if the given file is under the specified directory, 0 if not.
-Symlinks are taken into account in the file to find it's 'real' location
+Symlinks are taken into account in the file to find it's 'real' location.
=cut
sub is_under_directory
=head2 parse_http_url(url, [basehost, baseport, basepage, basessl])
-Given an absolute URL, returns the host, port, page and ssl components.
-Relative URLs can also be parsed, if the base information is provided
+Given an absolute URL, returns the host, port, page and ssl flag components.
+Relative URLs can also be parsed, if the base information is provided.
=cut
sub parse_http_url
Returns HTML for a JavaScript function called check_clicks that returns
true when first called, but false subsequently. Useful on onClick for
-critical buttons.
+critical buttons. Deprecated, as this method of preventing duplicate actions
+is un-reliable.
=cut
sub check_clicks_function
=head2 load_entities_map
Returns a hash ref containing mappings between HTML entities (like ouml) and
-ascii values (like 246)
+ascii values (like 246). Mainly for internal use.
=cut
sub load_entities_map
=head2 entities_to_ascii(string)
Given a string containing HTML entities like ö and 7, replace them
-with their ASCII equivalents
+with their ASCII equivalents.
=cut
sub entities_to_ascii
=head2 get_product_name
-Returns either 'webmin' or 'usermin'
+Returns either 'webmin' or 'usermin', depending on which program the current
+module is in. Useful for modules that can be installed into either.
=cut
sub get_product_name
return defined($gconfig{'userconfig'}) ? 'usermin' : 'webmin';
}
-$default_charset = "iso-8859-1";
-
=head2 get_charset
-Returns the character set for the current language
+Returns the character set for the current language, such as iso-8859-1.
=cut
sub get_charset
=head2 get_display_hostname
-Returns the system's hostname for UI display purposes
+Returns the system's hostname for UI display purposes. This may be different
+from the actual hostname if you administrator has configured it so in the
+Webmin Configuration module.
=cut
sub get_display_hostname
=head2 save_module_config([&config], [modulename])
-Saves the configuration for some module
+Saves the configuration for some module. The config parameter is an optional
+hash reference of names and values to save, which defaults to the global
+%config hash. The modulename parameter is the module to update the config
+file, which defaults to the current module.
=cut
sub save_module_config
=head2 save_user_module_config([&config], [modulename])
-Saves the user's Usermin configuration for some module
+Saves the user's Usermin preferences for some module. The config parameter is
+an optional hash reference of names and values to save, which defaults to the
+global %userconfig hash. The modulename parameter is the module to update the
+config file, which defaults to the current module.
=cut
sub save_user_module_config
=head2 nice_size(bytes, [min])
-Converts a number of bytes into a number of bytes, kb, mb or gb
+Converts a number of bytes into a number followed by a suffix like GB, MB
+or kB. Rounding is to two decimal digits.
=cut
sub nice_size
=head2 get_perl_path
-Returns the path to Perl currently in use
+Returns the path to Perl currently in use, such as /usr/bin/perl.
=cut
sub get_perl_path
=head2 get_goto_module([&mods])
Returns the details of a module that the current user should be re-directed
-to after logging in, or undef if none
+to after logging in, or undef if none. Useful for themes.
=cut
sub get_goto_module
return undef;
}
-=head2 select_all_link(field, form, text)
+=head2 select_all_link(field, form, [text])
Returns HTML for a 'Select all' link that uses Javascript to select
-multiple checkboxes with the same name
+multiple checkboxes with the same name. The parameters are :
+field - Name of the checkbox inputs.
+form - Index of the form on the page.
+text - Message for the link, defaulting to 'Select all'.
=cut
sub select_all_link
=head2 select_invert_link(field, form, text)
-Returns HTML for a 'Select all' link that uses Javascript to invert the
-selection on multiple checkboxes with the same name
+Returns HTML for an 'Invert selection' link that uses Javascript to invert the
+selection on multiple checkboxes with the same name. The parameters are :
+field - Name of the checkbox inputs.
+form - Index of the form on the page.
+text - Message for the link, defaulting to 'Invert selection'.
=cut
sub select_invert_link
=head2 select_rows_link(field, form, text, &rows)
Returns HTML for a link that uses Javascript to select rows with particular
-values for their checkboxes
+values for their checkboxes. The parameters are :
+field - Name of the checkbox inputs.
+form - Index of the form on the page.
+text - Message for the link, de
+rows - Reference to an array of 1 or 0 values, indicating which rows to check.
=cut
sub select_rows_link
=head2 check_pid_file(file)
-Given a pid file, returns the PID it contains if the process is running
+Given a pid file, returns the PID it contains if the process is running.
=cut
sub check_pid_file
=head2 get_mod_lib
-
-Return the local os-specific library name to this module
-
+Return the local os-specific library name to this module. For internal use only.
=cut
sub get_mod_lib
=head2 module_root_directory(module)
-Given a module name, returns its root directory
+Given a module name, returns its root directory. On a typical Webmin install,
+all modules are under the same directory - but it is theoretically possible to
+have more than one.
=cut
sub module_root_directory
=head2 list_mime_types
-Returns a list of all known MIME types and their extensions
+Returns a list of all known MIME types and their extensions, as a list of hash
+references with keys :
+type - The MIME type, like text/plain.
+exts - A list of extensions, like .doc and .avi.
+desc - A human-readable description for the MIME type.
=cut
sub list_mime_types
=head2 guess_mime_type(filename, [default])
-Given a file name like xxx.gif or foo.html, returns a guessed MIME type
+Given a file name like xxx.gif or foo.html, returns a guessed MIME type.
+The optional default parameter sets a default type of use if none is found,
+which defaults to application/octet-stream.
=cut
sub guess_mime_type
=head2 open_tempfile([handle], file, [no-error], [no-tempfile], [safe?])
-Returns a temporary file for writing to some actual file
+Returns a temporary file for writing to some actual file.
+XXX
=cut
sub open_tempfile
projects / webmin.git / commitdiff