[manpage_begin httpd::doc n 1.1] [copyright {2003 Andreas Kupries }] [titledesc {File handling}] [moddesc {Tcl Web Server}] [require httpd::doc [opt 1.1]] [description] The package [package httpd::doc] provides a domain for the serving of urls from the filesystem. This is also the domain through which the TML template facility is made available. It has additional tie-ins to the packages [package httpd::cgi] (CGI applications stored in the fileststem) and [package httpd::dirlist] (Directory listings as virtual files). [section {Public API}] [para] [list_begin definitions] [lst_item {Access control}] This package installs an access control callback which uses the package [package httpd::auth] to determine if an request for an url has to be denied or not. [call [cmd Doc_AddRoot] [arg virtual] [arg directory] [arg arg]...] This commands adds a mapping from the url prefix [arg virtual] to the [arg directory] in the filesystem. Any additional arguments will be given as options and values to the internal [cmd Url_PrefixInstall] call registering [arg virtual] as a new domain. [emph Note:] The last implies that from [package httpd::url]'s point of view each document root is a separate url domain. [call [cmd Doc_Root] [opt "[arg real] [arg arg]..."]] A convenient wrapper around [cmd Doc_AddRoot]. It not only installs the directory [arg real] as a document domain, but associates it with the root of the url tree on this server, i.e. [file /]. [nl] The command will return the name of the directory of that document root if no argument is specified. Otherwise it will set this document root and return the empty string. [nl] All arguments coming after are additional options and values which are given to [cmd Url_PrefixInstall]. [call [cmd Doc_RegisterRoot] [arg {virtual directory}]] Use this call to add a file system managed by any Domain Handler (e.g. CGI for example) to this package. This registers the mapping from urls in the domain to files, as required for [cmd Doc_Virtual]. [call [cmd Doc_Include] [arg filename]] Reads the contents of the file [arg filename] and substitutes them via [cmd subst] at the tcl stack level at which this procedure was called. The result of the substitution is returned as the result of the command. A relative path will be joined with the directory at the top of the include stack in global variable [var page(includeStack)]. [call [cmd Doc_PublicHtml] [opt [arg homedir]]] En- and disables the handling of urls of the form [file ~user/a/b/...] by mapping them to the subdirectory [arg homedir] of that users account. The command will by default use the subdirectory [file public_html] if no directory was specified explicitly. To disable the mapping invoke the command using the empty string for the name of the subdirectory. [call [cmd Doc_Virtual] [arg {sock curfile virtual}]] This command looks up the url [arg virtual] and returns the associated path in the filesystem. It will return the empty string if [arg virtual] is not managed by this package. [nl] If [arg virtual] is a relative url, then [arg curfile] has to be specified and will be treated as the [emph path] of the dcoument containing the reference to [arg virtual]. [nl] The argument [arg sock] represents the current connection. It is not used by the command. [call [cmd Doc_Handle] [arg {prefix path suffix sock}]] The main command for the handling of document urls. Exported for use by other domains which have to handle files. The first three arguments specify the url to handle, and the file associated with it. The last argument is the connection making the request. The command assumes that all these pieces actually match up with each other. [nl] The command directs requests for directories always to the package [package httpd::dirlist]. Otherwise it will determine the mime-type of the requested document and then either invoke a special handler for that type if such present or directly reply with the contents of that file if there is no special handler for the type. [nl] If the [arg path] does not exist in the filesystem then it will try to find an alternative it can serve. A not-found reply will be generated only if that fails too. It is this fallback mechanism which calls the template facility when necessary. [nl] The handler mechanism described above is also dependent on the existence of appropriate file extension to mime type mapping in the package [package httpd::mtype] as otherwise special files will not be recognized as such, i.e. the chosen mime type will be wrong. If a file [file mime.types] is present in the server library directory (residence of all packages) it will be read automatically during startup and used to set up a number of standard mappingsa to support the type specific handlers exported by the various server packages. [list_end] [see_also httpd httpd::url httpd::fallback] [see_also httpd::dirlist httpd::cookie httpd::auth] [see_also httpd::fallback httpd::mtype httpd::doc_error] [see_also httpd::cgi] [keywords {web server} documents filesystem] [manpage_end]