- acl_filename()
Returns the filename in which the list of users and their modules is
stored. For internal use only.
- additional_log(type, object, data) (Versions 0.81 and above)
When using file-change logging, this function adds an entry to the logs
for the current action. Useful if Webmin has not done this for you
automatically, for example if your code has run a command with a piped open
statements. You might use it like this :
open(PIPE, "somecommand |");
&additional_log("exec", undef, "somecommand");
The parameters to this function are :
- available_usermods(allmods, usermods) (Versions 1.000 and above)
Given a list of all modules and access control information, returns
a list of modules that the current Usermin user has access to.
Mainly for internal use by the Usermin main menu and themes. allmods
must be a reference to an array of module details as returned by get_all_module_infos,
while usermods must a reference to the array returned by list_usermods.
- backquote_logged(command) (Versions 0.81 and above)
This function is similar to the Perl backquote ` operator in that it
executes the given command and returns its output, but it also
records the command executed for later logging by webmin_log.
- check_ipaddress(string)
Returns 1 if the given string is a valid IP address like
10.254.1.100, 0 if not.
- check_os_support(moduleinfo)
Determines if the module whose details are in the moduleinfo
parameter is supported on this operating system or not. This must be
a hash reference of the kind returned by get_module_info or get_all_module_infos.
This function is mainly for internal use - if you just want to find
out if a module is available on this system, use foreign_check
instead.
- clean_environment() (Versions
0.91 and above)
Delete from the global environment %ENV all entries set by the Webmin
webserver, such as REMOTE_USER and anything starting with HTTP_.
This should be called before your CGI script starts a server
process such as Apache or Squid, so it doesn't get confused by
environment variables normally only visible to CGI programs.
- close_http_connection(handle) (Versions 0.90 and above)
Closes an HTTP session handle created by make_http_connection.
- complete_http_download(handle, destfile,
[error], [callback])
This function is used internally by http_download and ftp_download,
and should never be called directly by module developers.
- copydata(in, out)
Reads data from the filehandle in and writes it to out
until there is no more to read.
- create_user_config_dirs() (Versions 0.93 and above)
In Usermin, modules cannot store persistent configuration data in
their configuration directory $module_config_directory because
it is only writable by root. If you code wants to store settings on
a per-user basis, it should call this function which will set the
global variable $user_module_config_directory to
~currentuser/.usermin/modulename and ensure that the directory exists.
The files defaultuconfig in the
module's directory, uconfig in the module configuration
directory under /etc/webmin and config in the
user's module configuration directory will be read in that order
into the global hash %userconfig. See the "Creating
Usermin Modules" section for more details.
- date_chooser_button(dayfield, monthfield,
yearfield, [formno]) (Versions 0.83 and
above)
Returns HTML for a button that when clicked allows the user to select
a date. The dayfield parameter must be the name of a text input
into which the day will be placed, monthfield the name of
select input for the month, and yearfield the name of a text
input for the year. The formno if given is the number of the
form on the current page that contains the inputs.
- decode_base64(string)
Takes a string in base-64 encoded format and converts it back to
the normal form. This format is often used for email attachments and
passwords in HTTP requests. The opposite is encode_base64.
- disk_usage_kb(directory) (Versions 0.86 and above)
Returns the number of kilobytes used by the given directory and all the
files in it.
- encode_base64(string) (Versions 0.75 and above)
Returns the given string encoded in base64 format, with a return
at the end of each line (even if only one line is produced).
- error(message)
This function is typically used by CGI programs that process the
input from a form, to inform the user of invalid input or some
processing error by displaying the message parameter and
exiting. It assumes that error_setup has been called first
to set the first part of the error message, to which the parameter
will be appended. For example :
&error_setup("Failed to save user");
if (!$in{'name'}) { &error("Missing username"); }
if ($in{'name'} =~ /a/) { &error("'$in{'name'}' is not a valid username"); }
- error_setup(message)
Any code that calls error should call this function first to
specify that the message parameter should be prepended to all
future errors displayed.
- fast_wait_for(handle, string, ...)
This function works like wait_for, but matches exact strings
instead of regular expressions.
- file_chooser_button(field, type, form)
Returns HTML for a javascript button that allows the user to select
a file or directory on the server. The parameters are :
- filter_javascript(html) (Versions 0.93 and above)
Given the html for an entire webpage, this function attempts to
strip out or disable all Javascript and returns the result. If your
module displays HTML from an untrusted source (such as an email
message or file on the server), it should call this function on the
HTML in order to remove the potential security risk of malicious
Javascript, which could capture the session key for the current
Webmin login.
- find_byname(name)
Given a name, searches for processes matching that name and
returns their PIDs. If none are found, an empty list is returned.
- flush_file_lines()
Writes back to disk the arrays of lines for any files requested by
calling the read_file_lines function. A newline (\n) character
is added to each line.
- flush_webmin_caches() (Versions 0.980 and above)
Clears all the in-memory and on-disk caches used by web-lib.pl. This
function is really for internal use only.
- footer(link, text, [link, text], ...)
Outputs a small left-facing arrow and a link with the text "Return to text".
Any CGI program that calls header must also call this
function at the end in order to complete the page's HTML properly.
In Webmin versions 0.92 and above, you can
specify multiple link and text parameters to have the
function generate multiple footer links, like so :
&footer("", "module index", "list.cgi", "users list");
- foreign_call(module, function, [arg], ...) (Versions 0.70 and above)
Calls a function in another module, and returns the results. The module
parameter must by the module name, function the name of the
function to call in that module, and any remaining parameters the
arguments to pass to that function. For example :
&foreign_require("proc", "proc-lib.pl");
@procs = &foreign_call("proc", "list_processes");
&foreign_call("proc", "renice_proc", $pid, -10);
The example above calls the proc module to
get a list of processes, and then again to change the priority of
some process.
In Webmin versions 0.960 and above, you can use
the normal Perl syntax for calling functions in other modules, like
:
&foreign_require("proc", "proc-lib.pl");
@procs = &proc::list_processes();
&proc::renice_proc($pid, -10);
- foreign_check(module) (Versions 0.70 and above)
Checks if some other module exists and is supported under the
current operating system. If yes, return 1 - otherwise, returns 0.
You should call this before calling foreign_call to access
functions in other modules.
- foreign_config(module) (Versions 0.70 and above)
Returns a hash containing config options from the specified other module,
just like the %config hash set by init_config for
this module.
- foreign_require(module, file) (Versions 0.70 and above)
Before calling functions from another module with foreign_call(),
you must use this function to bring in the appropriate library. The module
parameter is the name of the module you want to call functions in,
and the file parameter the name of a library file in that
module directory.
- ftp_command(command, expected, [error])
Used by the ftp_download function to send a command to the
connected FTP server. Your module code should never call this function.
- ftp_download(host, file, destination,
[error], [callback])
Makes an FTP connection to some host and requests the download
of a file. The contents of this file are then stored in the
given destination file. If an FTP proxy is configured, the
download will be made via the proxy.
The optional error and callback
parameters are only supported in Webmin versions 0.93 and above, and
behave in exactly the same way as in the http_download
function, documented above.
- generate_icon(image, title, link, [href],
[width], [height])
Outputs HTML for an icon with the given image, title
below it and as a hyperlink to the relative or absolute URL in the link
parameter (if set). If the href parameter is supplied it will
be included in the <a href=> tag, so that you can point the link
to a different frame. The icon's size will be set to 48 x 48,
unless the width and height parameters are given.
- get_all_module_infos(cachemode) (Versions 0.950 and above)
Returns a list of hash references, each containing the details of one
installed module in the same format as returned by the standard get_module_info
function. In order to avoid having to read one file from each
module, this function usually caches the module details in the file /etc/webmin/module.infos.cache,
which can be read much faster.
If the cachemode parameter is set to 0,
normal caching of known modules is done. If it is set to 1, the
cache is not used at all. If set to 2 any existing cache will be
read but not written out.
- get_available_module_infos(cachemode)
Like get_all_module_infos, but only returns modules available
to the current Webmin or Usermin user instead of every one on the
system. The cachemode parameter is passed on to get_all_module_infos
and thus has exactly the same meaning.
- get_miniserv_config(hashref)
Fills in the hashref Perl hash reference parameter will the
configuration from Webmin's built-in web server, miniserv.pl.
This is generally read from /etc/webmin/miniserv.conf. The
opposite function is put_miniserv_config for writing out a
new configuration.
- get_module_acl([user], [module]) (Versions 0.72 and above)
Returns a hash containing the ACL for the given user and module.
If no user is specified, the current user is used. If no module is
specified, the calling module is user. See the "Module Access Control"
section for more information on module ACLs.
- get_module_info(module, noclone) (Versions 0.76 and above)
Returns a hash containing information about the given module,
with the keys desc, os_support and dir.
If the noclone parameter is set to 1, details of the underlying
module will be returned when requesting information on a cloned
module.
- get_system_hostname() (Versions 0.70 and above)
Returns the hostname of the system Webmin is running on. More reliable
that the standard Perl hostname() function, as it tries
several different methods.
- get_theme_info(theme) (Versions 0.92 and above)
Like get_module_info, but returns the details of a theme
from it's theme.info file.
- get_webmin_version() (Versions 0.70 and above)
Returns the version of Webmin this module is running under.
- group_chooser_button(field, multiple, form) (Versions 0.63 and above)
Just like the user_chooser_button function above, but for the
selection of groups instead.
- has_command(command)
Searches Webmin's PATH for the given command. Returns 1 if
found, 0 if not. If an absolute path is specified, the function
instead checks to see if it exists and is executable or not.
- header(title, image, [help], [config],
[noindex], [noroot], [text], [header], [body], [below])
The header function is used by almost all programs to output
the HTTP header line (Content-type: text/plain), HTML title,
background and title image. The parameters passed to this function are
:
If a theme is in use that defines its own theme_header
function, all of the above parameters will be passed to that function
instead. This means that they may be interpreted quite differently,
and the supplied title and other information placed in unexpected
locations depending on the theme in use.
If this function is called by a Usermin module
and the config parameter is set, your code must have called create_user_config_dirs
beforehand, in order to setup the ~/.usermin/modulename
directory. Instead of a Module Config link being included in the
header, one called Preferences will be instead, which allows the
user to edit his own personal settings for the module. The actual
settings that can be changed are determined by the uconfig.info
file in the module directory, which has the same format as config.info
described below.
Some themes have a custom header
function that puts all HTML output after the heading into a table.
Unfortunately, some browsers will not display a table's contents
until its ending HTML tag has been output. This means that if your
CGI program is producing some progressive output (such as the new
contents of a log file) or takes a long time to run, nothing will
be visible to the user until it completes. To avoid this, the
special global variable $theme_no_table should be set to 1
before header is called, indicating that page content
should not be put in an HTML table.
- help_file(module, page)
Returns the full path to the file containing the HTML for the given
help page in the specified module. Files for the user's
chosen language are used in preference to English, if they exist. This
function is mainly for internal use only though.
- help_search_link(terms, section, ...) (Versions 0.86 and above)
Returns HTML for a link to the System Documentation module for
searching for the given terms. The section parameters
after the terms determine what documentation is searched, and each
can be one of
The return value from this function can be passed
as the 7th parameter to the header function on the main
page of your module, creating a link to additional info in man
pages or README files. For example :
&header("The Foo Module", undef, undef, 1, 1, undef,
&help_search_link("foo", "man", "doc", "google"));
- hlink(text, page) (Versions
0.63 and above)
Returns HTML for a link to a help page. The text parameter is
the text of the link and page the name of the help page.
See the "Online Help" section for more information.
- html_escape(string)
Given a text string, converts the characters <, > and
& to <, > and & respectively, among
others. It should be used when text from some source that may
contain HTML characters is going to be included in a page generated
by your module, so that the text appears exactly as it should and
potentially malicious HTML code (perhaps containing Javascript) is
neutralized.
- http_download(host, port, page, destination,
[error], [callback])
Makes a HTTP connection to a webserver host and port to
request some page. The contents of this page are then
stored in the destination file. If the user has configured
his Webmin installation to use a proxy server, then the HTTP
request will go through that proxy.
The optional error and callback
functions are only supported in Webmin versions 0.93 and above. If error
is supplied, it must be a reference to a scalar that will be set
with an error message if the download fails, instead of the
function simply calling the standard error function in the
case of a failure.
The callback parameter can be a
reference to a function that will be called back to at various
stages of the download process. When called, the first parameter
indicates the status, and the second some additional information.
Possible status codes are :
- Server has been contacted
The second parameter is 1 if the requested URL is a redirect, or 0 if
a normal file.
- Download has started
The second parameter is the size of the file being downloaded, if it
is known.
- Some data has been received
The second parameter is the amount of data received so far. This will
be called for every 1kb (or less) of data received.
- Download complete
The URL has been totally downloaded. No second parameter is supplied.
- Redirected to new URL
The second parameter is the new URL to which the request has been
redirected.
If you just want to display the progress of a
download in the way that some of the code Webmin modules do, the
standard function progress_callback can be passed as the
6th parameter to http_download. However, you must set the
global variable $progress_callback_url to the URL or name
of the file being downloaded, for use in the progress messages.
- icons_table(links, titles, icons, [columns],
[href], [width], [height])
The main Webmin page and many modules use grids of icons, each linking
to a different option, domain, share or suchlike. This function
generates an icons grid based on the lists given as parameters. links
is a reference to an array of URLs, titles a reference to an
array of messages to appear below icons, and icons a reference
to an array of image URLs.
If the columns parameter is given, it
specified the number of icons to display per row. The default is
for each row will contain 4 icons. The href, width
and height parameters have exactly the same meaning as in the generate_icon
function, which this one actually calls to create each icon.
- include(file)
Copies the content from the given file to STDOUT.
- indexof(value, array)
Returns the index of some value in the array which
comprises the rest of the parameters, or -1 if not found.
- init_config()
Initializes global configuration variables. See the "Module CGI
Programs" section for more details.
Note that prior to version 0.73, the init_config function had
to be passed the name of the module as a parameter. From 0.73 onwards,
the module name is worked out automatically.
- is_under_directory(directory, file) (Versions 1.030 and above)
Returns 1 if the given file is under the specified directory,
0 if not. Both must be absolute paths. If the file is actually a
symbolic link, its target must be under the directory for the
function to return 1. This can be useful in modules that enforce
restrictions on the directories that users are allowed to edit files
in.
- kill_byname(name, signal) Given a name,
searches for processes matching that name and kills them
with the given signal.
- kill_byname_logged(name, signal) (Versions 0.91 and above)
Like the kill_logged function, but also records the
command executed for later logging by webmin_log.
- kill_logged(signal, pid, ...) (Versions 0.81 and above)
This function is exactly the same as the Perl kill statement,
but also records the signal and PIDs for later logging by webmin_log.
- list_languages() (Versions
0.76 and above)
Returns a list of hash references, each containing the details of a
supported language. This function is generally for internal use only.
- list_usermods() (Versions
1.000 and above)
Returns an array containing information about which Usermin users can
have access to which modules. For internal use only.
- load_language(module)
Returns a hash containg translations for some module, just like
the %text hash that init_config sets for this
module.
- load_theme_library()
Reads the theme.pl file for the current theme, if one exists
and if it has not been loaded yet. This is another internal use
only function that module writers should not call.
- lock_file(file) (Versions
0.81 and above)
Obtains an exclusive lock on the given file, if necessary
waiting until the lock is released if it is held by another
program. Locking is done by creating a .lock file contain
the PID of the process, which guarantees that locks will not be
held forever by dead processes. Locks can be made on files,
directories and symbolic links, and should be made before any of
those are created, modified or deleted.
- make_date(time_t)
Given a Unix time_t value (seconds since 1970), returns a
date-time string in the format dd/mm/yyyy hh:mm
- make_http_connection(host, port, ssl, method,
page) (Versions 0.90 and above)
A general function for making an HTTP connection, possibly using
SSL. The function will attempt to connect to the given host and port
(in SSL mode if the ssl flag is set), through a proxy server
if you have one configured in Webmin. It will then make an HTTP
request using the given method and page, and return
a session handle reference if no errors are encountered. If any
error does occur in the connection, a scalar error string will be
returned.
The returned session handle should be used with
the read_http_connection and write_http_connection
functions to send any additional headers and to read back the response
headers and body. When done, the close_http_connection
function should be called with the session handle.
- no_proxy(host)
Returns 1 if Webmin will connect directly to the given host for
HTTP requests, or 0 if a proxy will be used. Mainly for internal use by
the various HTTP-related functions.
- open_socket(host, port, handle, [error])
- Attempts to open a TCP connection to the
specified host and port using the given Perl file handle.
Once this function returns the caller can read from or write to the
handle to communicate with a remote system, and call close
on it when done. If the connection cannot be made the error
function is called with a message explaining what went wrong, unless
the error parameter to this function has been set as a
scalar reference. If so, the error message is place in that
variable and the function returns 0 (instead of the usual return
value of 1).
- other_groups(user) (Versions
0.82 and above)
Returns a list of secondary groups to which the Unix user
belongs.
- PrintHeader([charset])
Outputs the Content-type: text/html header (and possibly
others) that all CGI programs which produce HTML much generate. If
the charset parameter is given, it specifies the character set
of the HTML. Normally this function is not called directly -
instead, header will it for you with the right character
set for the user's language.
- progress_callback(action, details)
This function exists to be passed to http_download so that
download progress reports will be printed. Calling it directly from
your code makes no sense.
- put_miniserv_config(hashref)
Writes the configure from the hash reference parameter hashref
to the configuration file used by Webmin's built-in webserver. You will
need to call restart_miniserv for this change to have any
effect though.
- ReadParse()
This function takes any CGI parameters passed to your program (from
form inputs or after the ? in the URL) and places them in the
associative array %in. If a CGI parameter has multiple
values (for example, from a list that allows multiple selections)
then those values are separated by null characters ('\0' in perl).
- ReadParseMime()
When writing a CGI program that handles input from a form using enctype=multipart/form-data
this function must be called instead of ReadParse() to fill
the %in array with form inputs. You must add the enctype
tag to any forms using file-upload inputs.
- read_acl([hashref1], [hashref2])
This function fetches the current list of which Webmin user has access
to which modules and stores it in the hashes referenced by the two
parameters. hashref1 will be filled in as a two-key hash, in
which the first key is a username and the second a module name. hashref2
will be filled in with usernames, each referring to an array of
modules that the user has. For example :
&read_acl(\%hash1, \%hash2);
print "User $remote_user has access to Users and Groups<br>\n"
if ($hash1{$remote_user,'useradmin'});
print "User $remote_user has access to ",
join(" ", @{$hash2{$remote_user}}),"<br>\n";
- read_env_file(file, hash) (Versions 0.79 and above)
Reads a file of /bin/sh variable assignments in key=value or key
= "value" format into the given hash reference.
- read_file(file, hash)
Reads a file in key=value format into the given hash
reference.
- read_file_cached(file, hash) (Versions 0.950 and above)
Like the standard read_file function documented above, but
keeps a cache of files read in order to avoid reading them multiple
times. Mostly for internal use at the moment.
- read_file_lines(file)
Returns a reference to an array containing the lines from the given file,
with any newline (\n) characters removed. The caller can then
modify this array by adding, removing or changing lines using functions
like push and splice. flush_file_lines can
then be called to write changes back to the original files.
- read_http_connection(handle, [amount]) (Versions 0.90 and above)
Reads either a single line from the given session handle
returned by make_http_connection, or the specified number
of bytes if the amount parameter is supplied.
- redirect(url)
Given a relative or absolute url, outputs a HTTP header to
redirect the browser to that URL. This function will not work if
called after header, and vice-versa.
- remote_error_setup(handler) (Versions 0.93 and above)
Normally, when one of the remote_* functions encounters an
error (such as the remote Webmin server being down), it will call
the standard error function which will cause your CGI program
to exit. However, if you use this function to register an alternate
error handler, it will be called instead, and the remote
function will return its return value.
- remote_eval(server, module, code) (Versions 0.82 and above)
Executes some perl code on a remote Webmin server in the
context of the given module. This can be very useful if you
want to do something that is not possible by calling a function
with remote_foreign_call. However, you must first call remote_foreign_require
with the same server and module before using this function.
- remote_finished() (Versions
0.82 and above)
This function should be called by any CGI that makes use of any of the
other remote_ functions once it has finshed calling them, in
order to clean up connections to the remote servers. It is not strictly
necessary though as the connections will timeout after 10 seconds of
inactivity. Also, when using fast RPC this never needs to be called
as remote sessions will exit as soon as your CGI finishes.
- remote_foreign_call(server, module, function,
[arg], ...) (Versions 0.82 and above)
Calls a function in some module on another server
and returns the results. You must already have called remote_foreign_require
for the same server and module before trying to use this function.
The function parameter is the name of a function to call in
the remote module, and the arg parameters after it are
arguments that will be passed to it. For example :
&remote_foreign_require("www.blah.com", "apache", "apache-lib.pl");
@servers = &remote_foreign_call("www.blah.com", "apache", "get_config");
As the example shows, the remote_foreign_call
function returns whatever is returned by the function on the remote
server.
- remote_foreign_check(server, module) (Versions 0.82 and above)
Checks if a module exists and is supported on a remote Webmin server.
If yes, return 1 - otherwise, returns 0. If in doubt, you should call
this before calling remote_foreign_call to access functions in
other modules on another server.
- remote_foreign_config(server, module) (Versions 0.90 and above)
This function is similar to foreign_config, but is for
fetching a module configuration from a remote server
instead. But unlike foreign_config it returns a hash
reference rather than a hash.
- remote_foreign_require(server, module, file) (Versions 0.82 and above)
The remote_ series of functions are similar to the foreign_
functions, but instead of just allowing you to call code in another
module they allow you to call code on another Webmin server. Each
server that you want to call remote functions on must first be
registered in the Webmin Servers module, with the Link type
option set to Login via Webmin and a username and password
entered.
Before calling functions from a module on
another server with remote_foreign_call, you must use
this function to bring in the appropriate library. The server
parameter is the hostname of the remote Webmin server, the module
parameter is the name of the module you want to call functions in,
and the file parameter the name of a library file in that module
directory.
- remote_write(server, localfile, [remotefile]) (Versions 0.90 and above)
If when making remote function calls you need to transfer a large
amount of data to a remote server, this function should be
used instead of passing it in a scalar through remote_foreign_call.
The localfile parameter is a file on the server the function
is called on, and the remotefile parameter the name of a
file on the remote server to which the contents of localfile
will be copied. If remotefile is omitted, a random temporary
filename will be chosen instead and returned from the function.
- remote_read(server, localfile, remotefile) (Versions 0.90 and above)
This is the opposite of remote_write, in that it copies data
from a file on a remote webmin server into a local file.
- remote_rpc_call(server, command) (Versions 0.90 and above)
This internal function is used by all of the other remote_*
functions to actually open a connection to the specified server
and send the command structure tell it what to do. You should
never call it directly.
- rename_logged(old, new) (Versions 0.81 and above)
Renames a file like the Perl rename function, but also records
the event for later logging by webmin_log. While you could
just lock the old and new files before renaming, that
would generate two large and rather useless diffs.
- replace_file_line(file, line, [newline], ...)
This function removes one line from a file and replaces
it with 0 or more new lines from the newline parameters.
This is done by reading the entire file into memory and writing out
the modified version.
- reset_environment() (Versions
0.91 and above)
Returns the environment to the state it had before the last call to clean_environment.
- resolve_links(file) (Versions
0.950 and above)
Given a file name that may contain symbolic links somewhere in
it's path, returns the actual real filename that it refers to.
Unlike the Perl readlink function, this also resolves
symbolic links in directories along the path as well.
- restart_miniserv()
Re-starts Webmin's built-in webserver, forcing it to re-load its
configuration. This function is mainly used by the Webmin Configuration
module, and is probably of little use to the average module coder.
- same_file(file1, file2) (Versions 0.950 and above)
Returns 1 if file1 and file2 refer to the same actual
file, by comparing inode numbers.
- save_module_acl(acl, [user], [module]) (Versions 0.72 and above)
Saves the given module ACL hash. If no user is specified, the current
user is used. If no module is specified, the caller's module is user.
See the "Module Access Control" section for more information on module
ACLs.
- seed_random() (Versions
0.85 and above)
Seeds the Perl random number generator so that calls to rand
will return truly random results. Uses /dev/urandom if
available, or the current time and process ID otherwise.
- serialise_variable(variable)
Converts the given Perl scalar or reference variable into a
text string. This function is mainly used by the various RPC-related remote_*
functions for encoding parameters and return values, but you may
find it useful for persistently storing Perl objects. The unserialise_variable
function does the reverse.
- switch_to_remote_user() (Versions 0.93 and above)
This function should only be called by code in Usermin modules, and
will switch the UID and GID of the current process to those of the Unix
user whose login matches the current Usermin login. If your Usermin
module can run with normal user permissions (and most can), you should
call this function after init_config in your module's library.
In addition to switching the UID, this function
also sets the global variable @remote_user_info to the
details of the Unix user, as returned by the getpwnam Perl
function.
- sysprint(handle, value, ...)
Calls the perl syswrite function to print the values
to the given file handle without any buffering.
- system_logged(command) (Versions 0.81 and above)
This function is exactly the same as the Perl system
statement, but also records the command executed for later
logging by webmin_log.
- tempname()
Returns a pathname in /tmp that can be used as a temporary
file. The actual filename will always be under the /tmp/.webmin
directory, which is only writable by root but world readable, so if your
temp file is going to contain security-critical information it should
be chowned to mode 700 before writing.
- terror(string)
Like a combination of the error function and the %text
array. A call to &terror('foo') is exactly the same as &error($text{'foo'}).
This function really just exists to make calling error more
convenient in an internationalized module.
- text(message, [parameter], ...) (Versions 0.75 and above)
Looks up the given message in the appropriate language
translation file, replaces the text $1, $2 and
so on with the rest of the parameters, and returns the
result. See the section on "Internationalisation" for more.
- to_ipaddress(hostname)
Given a hostname, this function returns a string like
10.254.1.100 representing the IP addresss for that hostname, or
undef if none was found. If the parameter is already an IP address
it is returned unchanged.
- trunc(string, length)
Truncates a string of space-separated words so that it is less
than or equals to the given length, without chopping off
part of a word.
- unique(value, ...)
Given a list of values, returns an array with duplicates
removed.
- unix_group_input(field, group, [form])
Returns HTML for a text box named field for entering a group
name, with a button next to it that pops up a window for selecting
a group. The group parameter sets the initial value for the
field. If the field is not on the page's first form, the form
parameter should be set to the correct form number.
- unix_user_input(field, user, [form])
Returns HTML for a text box named field for entering a username,
with a button next to it that pops up a window for selecting a user.
The user parameter sets the initial value for the field. If
the field is not on the page's first form, the form
parameter should be set to the correct form number.
- unlock_all_files() (Versions
0.81 and above)
Releases all locks currently held by this program, by calling unlock_file
multiple times.
- unlock_file(file) (Versions
0.81 and above)
Releases a lock on file grabbed by the lock_file
function. If the logging of file changes is enabled, a diff of the
old and new file contents will be done when this function is
called.
- unserialise_variable(string)
Converts a string created by serialise_variable back
into a Perl scalar or reference of some kind.
- un_urlize(string)
Decodes the special URL escape sequences in the given string and
returns the original text. For example, hello%20world%21 would
be converted to hello world!.
- urlize(string)
Converts an arbitrary string to a form suitable for use in a
URL. For example, don't jump! would be converted to don%27t%20jump%21.
- user_chooser_button(field, multiple, form) (Versions 0.63 and above)
Returns HTML for a javascript button that allows the Webmin user to
select a user or users from those on the server. The parameters are
:
- wait_for(filehandle, regexp, ...)
Given a perl filehandle and a list of regular expressions in the
regexp parameters, this function reads from the filehandle
until one of the expressions matches. It then returns the regexp
number, and fills the global array @matches with the values of
any bracketed sections of the matching expression. It can be useful
for interacting with other programs or servers that would normally
take user input, as this example shows :
&open_socket("somehost", 23, TELNET);
select(TELNET);
$| = 1;
select(STDOUT);
while(1) {
my $rv = &wait_for(TELNET, "login:", "password:", ">");
if ($rv == 0) {
print TELNET "fred\n";
}
elsif ($rv == 1) {
print TELNET "mypassword\n";
}
elsif ($rv == 2) {
print TELNET "ls -la\n";
close(TELNET);
break;
}
else {
&error("Telnet failed!");
}
}
- webmin_log(action, type, object, params) (Versions 0.81 and above)
As explained in the "Action Logging" section, this function writes
to the detailed logfile the given parameters identifying the action
performed by the calling program.
- write_env_file(file, hash, export) (Versions 0.79 and above)
Writes the contents of a hash reference to the given file
in /bin/sh variable assignment format. If the export parameter is
non-zero each variable assignment is preceded with export.
- write_file(file, hash)
Writes the contents of a hash reference to the given file
in key=value format. This can be read in by the read_file
function.
- write_http_connection(handle, [data], ...) (Versions 0.90 and above)
Writes the given data strings to the HTTP session handle.