60.1. API Functions
The web-lib.pl file contains a number of functions useful for generating HTML, parsing files, and all the other things Webmin modules need to do. The functions available in Webmin 1.060 are listed below in alphabetical order. The possible parameters for each function are shown as well, with those that are optional surrounded by [ ]. The text ... in the parameter list indicates that the previous one can be repeated an arbitrary number of times.
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) When using file-change logging, this function adds an entry to the logs for the current action. This function is useful if Webmin has not done this for you automatically, for example, if your code has run a command with a piped open statement. You might use it like this:
open(PIPE, "somecommand |"); &additional_log("exec", undef, "somecommand");The parameters of this function are:
type Must be one of exec (for logging commands run), modify (for a file change), or sql (for an executed SQL statement).
object The full path to the file modified for file change logs, or undef otherwise.
data The shell command-run, diff output for the modified file or the executed SQL statement.
available_usermods(allmods, usermods) Given a list of all modules and access control information, this function returns a list of modules to which the current Usermin user has access. This is 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 be a reference to the array returned by list_usermods.
backquote_logged(command) 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, and returns 0 if not.
check_os_support(moduleinfo) Determines whether or not the module whose details are in the moduleinfo parameter is supported on this operating system. 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() Deletes all entries set by the Webmin web server from the %ENV global environment, 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) 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 in filehandle and writes it to out until there is no more to read.
create_user_config_dirs() In Usermin, modules cannot store persistent configuration data in their configuration directory, $module_config_directory, because it is only writeable by root. If your 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 defaultuconfig files 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 Section 56.9 “Creating Usermin Modules” for more details.
date_chooser_button(dayfield, monthfield, yearfield, [formno]) 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) Returns the number of kilobytes used by the given directory and all the files in it.
encode_base64(string) 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. This is demonstrated in the following 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 displayed errors.
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:
field - The name of the HTML field into which the chosen filename will be placed.
filter_javascript(html) Given the html for an entire web page, 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 the arrays of lines for any files requested back to disk by calling the read_file_lines function. A new line character is added to each line.
flush_webmin_caches() 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], ..., [noendbody]) This function 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 to properly complete the page's HTML.
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");If the noendbody parameter is set to 1, the footer function will not produce </body> and </html> tags to properly end the page. It can be used if your program needs to output something after the normal footer. You must remember to print those tags yourself, however, so the HTML page is properly completed.
foreign_call(module, function, [arg], ...) This calls a function in another module and returns the results. The module parameter must be the module name, function must be the name of the function to call in that module, and any remaining parameters must be 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 calls the proc module to get a list of processes and then 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) Checks if some other module exists and is supported under the current operating system. If yes, it returns 1, otherwise, it returns 0. You should call this before calling foreign_call to access functions in other modules.
foreign_config(module) Returns a hash containing configuration options from the specified other module, just like the %config hash set by init_config for this module.
foreign_require(module, file) 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 in which you want to call functions and the file parameter is the name of a library file in that module directory.
ftp_command(command, expected, [error]) This is 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 earlier.
generate_icon(image, title, link, [href], [width], [height]) This outputs HTML for an icon with the given image and 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) This 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. To avoid having to read one file from each module, this function usually caches the module details in the /etc/webmin/module.infos.cache file, 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 it is set to 2, any existing cache will be read but not written out.
get_available_module_infos(cachemode) This is similar to 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) This fills in the hashref Perl hash reference parameter with 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]) This 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 Section 56.1 “Module Access Control” for more information on module ACLs.
get_module_info(module, noclone) This 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 instead of the details of the clone.
get_system_hostname() This returns the hostname of the system on which Webmin is running. It is more reliable than the standard Perl hostname function, as it tries several different methods.
get_theme_info(theme) This is similar to get_module_info, but returns the details of a theme from its theme.info file.
get_webmin_version() This returns the version of Webmin under which this module is running.
group_chooser_button(field, multiple, form) This is like the user_chooser_button function, but used for the selection of groups instead.
has_command(command) This searches Webmin's PATH for the given command. Returns 1 if found, and 0 if not. If an absolute path is specified, the function checks to see if it exists and whether or not it is executable.
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/html), HTML title, background, and title image. The parameters passed to this function are:
title The HTML title of this page. Also used as the ALT text for the title image.
image The URL of an image to display at the top of the page instead of the text from title. This should always be set to an empty string.
help If this parameter is defined, then a Help link is added to the title on the left-hand side, linking to the given help page.
config If this parameter is non-zero, a Module Config link is added to the left of the title. This links to a CGI program that allows the user to edit the configuration of this module, as defined by the config.info file. See Section 55.4 “Module Configuration” for more details.
noindex By default, the header function will add a Module Index link to the left of the title image linking to the index for this module. If this parameter is given and non-zero, this link will not be displayed.
noroot By default, a Webmin Index link to the Webmin main menu will be added to the left of the title image. If given, this parameter will suppress the addition of that link.
text HTML to be displayed to the right of the title image. This can be anything you like, as long as it fits in the small area available.
header HTML to be displayed in the <head> section of the page.
body Extra HTML tags to be include in the <body> tag.
below HTML to be displayed below the header. Often this is used on modules' main pages to show the version of the server that the module is configuring.
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 may be 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 to set up the ~/.usermin/modulename directory. Instead of a Module Config link being included in the header, one called Preferences will be included 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.
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 generated. 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) This 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.
help_search_link(terms, section, ...) This 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 following:
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 manual 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)This returns HTML for a link to a help page. The text parameter is the text of the link and page is the name of the help page. See Section 55.7 “Online Help” for more information.
html_escape(string) Given a text string, this converts the characters <, >, and & to <, >, and &, respectively, among others. It should be used when text from a particular source that may contain HTML characters is going to be included in a page generated by your module, so 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]) This makes an HTTP connection to a web server host and port request a 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 is 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.
The callback parameter can be a reference to a function to which it will be called back at various stages of the download process. When called, the first parameter indicates the status and the second indicates specific additional information. Possible status codes are:
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. You must, however, set the global variable $progress_callback_url to the URL or name of the file being downloaded, for use in the progress messages.
include(file) This copies the content from the given file to STDOUT.
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 something related. This function generates an icons grid based on the lists given as parameters. links is a reference to an array of URLs, titles is a reference to an array of messages that appear below icons, and icons is a reference to an array of image URLs.
If the columns parameter is given, it specifies the number of icons to display per row. The default is for each row to contain four icons. The href, width, and height parameters have exactly the same meaning as in the generate_icon function, which this function actually calls to create each icon.
indexof(value, array) This returns the index of some value in the array that comprises the rest of the parameters, or -1 if not found.
init_config() This initializes global configuration variables. See Section 55.3 “Module CGI Programs” for more details. Please note that the init_config function had to be passed the name of the module as a parameter prior to version 0.73. From 0.73 onwards, the module name is worked out automatically.
is_under_directory(directory, file) This returns 1 if the given file is under the specified directory, 0 if it is 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 in which users are allowed to edit files.
kill_byname(name, signal) Given a name, this searches for processes matching that name and kills them with the given signal.
kill_byname_logged(name, signal) This is like the kill_byname function, but also records the command executed for later logging by webmin_log.
kill_logged(signal, pid, ...) 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() This returns a list of hash references, each containing the details of a supported language. This function is generally for internal use only.
list_usermods() This returns an array containing information about which Usermin users can have access to certain modules. For internal use only.
load_language(module) This returns a hash containing translations for some module, just like the %text hash that init_config sets for this module.
load_theme_library() This 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) This function obtains an exclusive lock on a 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), this returns a date-time string in the dd/mm/yyyy hh:mm format.
make_http_connection(host, port, ssl, method, page) This is 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) This returns 1 if Webmin will connect directly to the given host for HTTP requests. It returns 0 if a proxy will be used. This is mainly for internal use by the various HTTP-related functions.
open_socket(host, port, handle, [error]) This function 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 placed in that variable and the function returns 0 (instead of the usual return value of 1).
other_groups(user) This returns a list of secondary groups to which the UNIX user belongs.
PrintHeader([charset]) This outputs the Content-type: text/html header (and possibly others) that all CGI programs that produce HTML must generate. If the charset parameter is given, it specifies the character set of the HTML. This function is not generally called directly. Instead, the header function will do 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) This writes the configuration from the hash reference parameter hashref to the configuration file used by Webmin's built-in webserver. You will need to call restart_miniserv, however, for this change to have any effect.
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 %in associative array. If a CGI parameter has multiple values (for example, from a list that allows multiple selections), then those values are separated by null characters ( 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 those to which the Webmin user has access 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> " if ($hash1{$remote_user,'useradmin'}); print "User $remote_user has access to ", join(" ", @{$hash2{$remote_user}}),"<br> "; read_env_file(file, hash)This reads a file of /bin/sh variable assignments in key=value or key="value" format into the given hash reference.
read_file(file, hash) This reads a file in key=value format into the given hash reference.
read_file_cached(file, hash) This is like the standard read_file function, but it keeps a cache of files read in order to avoid reading them multiple times. This is mostly for internal use at the moment.
read_file_lines(file) This returns a reference to an array containing the lines from the given file, with any newline 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]) This 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, this outputs an 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) When one of the remote_ functions encounters an error (such as the remote Webmin server being down), it will generally call the standard error function, which will cause your CGI program to exit. If you use this function to register an alternate error handler, however, it will be called, instead, and the remote function will return its return value.
remote_eval(server, module, code) This executes specific 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. You must, however, first call remote_foreign_require with the same server and module before using this function.
remote_finished() This function should be called by any CGI that makes use of any of the other remote_ functions once it has finished calling them, to clean up connections to the remote servers. It is not strictly necessary, however, as the connections will timeout after 30 seconds of inactivity. When using fast RPC, this also never needs to be called as remote sessions will exit as soon as your CGI finishes.
remote_foreign_call(server, module, function, [arg], ...) This 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) This checks to see if a module exists and is supported on a remote Webmin server. If yes, it returns 1, otherwise it returns 0. If in doubt, you should call this before calling remote_foreign_call to access functions in other modules on other servers.
remote_foreign_config(server, module) This function is similar to foreign_config, but is for fetching a module configuration from a remote server instead. Unlike foreign_config, however, it returns a hash reference rather than a hash.
remote_foreign_require(server, module, file) 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 in which you want to call functions, and the file parameter is the name of a library file in that module directory.
remote_write(server, localfile, [remotefile]) 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 on which the function is called, and the remotefile parameter is 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) 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) 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 to tell it what to do. You should never call it directly.
rename_logged(old, new) This 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 file differences.
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() This returns the environment to the state it had before the last call to clean_environment.
resolve_links(file) Given a file name that may contain symbolic links somewhere in its path, this function returns the actual real filename to which it refers. Unlike the Perl readlink function, this also resolves symbolic links in directories along the path as well.
restart_miniserv() This restarts Webmin's built-in web server, forcing it to reload 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) This returns 1 if file1 and file2 refer to the same actual file, by comparing inode numbers.
save_module_acl(acl, [user], [module]) This 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 used. See Section 56.1 “Module Access Control” for more information on module ACLs.
seed_random() This seeds the Perl random number generator so calls to rand will return truly random results. It uses /dev/urandom if it is available, or the current time and process ID otherwise.
serialise_variable(variable) This 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() 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. You should call this function after init_config in your module's library if your Usermin module can run with normal user permissions (and most can).
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, ...) This calls the Perl syswrite function to print the values of the given file handle without any buffering.
system_logged(command) 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 writeable by root but is world readable. If your temp file is going to contain security-critical information, it should have its UNIX permissions changed to mode 700 before writing.
terror(string) This is 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], ...) This function 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 “Internationalization” in Chapter 56 for more information.
to_ipaddress(hostname) Given a hostname, this function returns a string like 10.254.1.100 representing the IP address for that hostname, or undef if none was found. If the parameter is already an IP address, it is returned unchanged.
trunc(string, length) This truncates a string of space-separated words so that it is less than or equal to the given length, without chopping off part of a word. It is useful for word-wrapping output to a fixed width.
unique(value, ...) This is given a list of values and returns an array with duplicates removed.
unix_group_input(field, group) This 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.
unix_user_input(field, user) This 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.
unlock_all_files() This function releases all locks currently held by this program by calling unlock_file multiple times.
unlock_file(file) This releases a lock on file grabbed by the lock_file function. If the logging of file changes is enabled, a difference comparison between the old and new file contents will be done when this function is called. This comparison is done using the standard diff command.
unserialise_variable(string) This converts a string created by serialise_variable back into a Perl scalar or a reference of some kind.
un_urlize(string) This function 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) This converts an arbitrary string to a form suitable for use in a URL. For example, don't jump! will be converted to don%27t%20jump%21.
user_chooser_button(field, multiple, form) This 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:
field The name of the HTML file into which the chosen user or users will be placed.
multiple 0 for selecting a single user, 1 for selecting multiple users.
wait_for(filehandle, regexp, ...) Given a Perl filehandle and a list of regular expressions in the regexp parameters, this function reads from the file handle until one of the expressions matches. It then returns the regular expression number and fills the @matches global array with the values of any bracketed sections of the matching expression. If an error occurs while reading the input (perhaps because there is no more to read), -1 is returned instead. It can be useful for interacting with other programs or servers that would normally take user input, as the following 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 "; } elsif ($rv == 1) { print TELNET "mypassword "; } elsif ($rv == 2) { print TELNET "ls -la "; close(TELNET); break; } else { &error("Telnet failed!"); } }webmin_log(action, type, object, params) As explained in the “Action Logging” section of Chapter 56, this function writes the given parameters identifying the action performed by the calling program to the detailed log file.
write_env_file(file, hash, export) This function 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) This 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], ...) This function writes the given data strings to the HTTP session handle.