Location (Filesystem) Modules

mapping|Stdio.File|int(-1..0) find_file( string path, RequestID id )

The return value is either a response mapping, an open file descriptor or 0, signifying that your module did not handle the request. Return -1 to indicate the resource being a directory.

This is the fundamental method of all location modules and is, as such, required. It will be called to handle all accesses below the module's mount point. The path argument contains the path to the resource, in the module's own name space, and the id argument contains the request information object.

That the path is in the modules name space means that the path will only contain the part of the URL after the module's mount point. If a module is mounted on /here/ and a user requests /here/it/is.jpg, the module will be called with a path of it/is.jpg. That way, the administrator can set the mount point to anything she wants, and the module will keep working.

Note!

Changing the mount point to /here would give the module the path /it/is.jpg for that request.

A zero return value means that the module could not find the requested resource. In that case Roxen will move on and try to find the resource in in other location modules. Returning -1 means that the requested resource is a directory, in which case the request will be handled by a directory type module.

If the module could handle the request, the return value is either a response mapping or a Stdio.File object containing the requested file.

string query_location()

Returns the location in the virtual server's where your location module is mounted. If you make a location module and leave out this method, the default behaviour inherited from module.pike will return the value of the module variable 'location'.

Stat stat_file( string path, RequestID id )

The stat_file() method emulates Pike's file_stat() method, returning information about a file or directory. path is the path to the file or directory in the module's name space, id is the request information object.

stat_file() is most commonly used by directory type modules to provide informative directory listings, or by the ftp protocol module to create directory listings.

The return value it is expected to be a Stat array (or, in future versions, a Stdio.Stat object, for instance created from such an array):

({ mode, size, atime, mtime, ctime, uid, gid })

mode is an integer containing the Unix file permissions of the file. It can be ignored.

size is an integer containing the size of the file, or a special value in case the object is not actually a file. Minus two means that it is a directory, minus three that it is a symbolic link and minus four that it is a device special file. This value must be given.

atime is a unixtime integer containing the last time the file was accessed (seconds since 1970). It can be ignored.

mtime is a unixtime integer containing the last time the file was modified (seconds since 1970). It will be used to handle Last-Modified-Since requests and should be supplied if possible.

ctime is a unixtime integer containing the time the file was created (seconds since 1970). It can be ignored.

uid is an integer containing the user id of this file. It will be correlated with the information from the current authentification type module, and used by the CGI executable support module to start CGI scripts as the correct user. It is only necessary for location modules that provide access to a real file system and that implement the real_file() method.

gid is an integer containing the group id of the file. It is needed when uid is needed.

mapping(string:Stat) find_dir_stat( string path, RequestID id )

Need not be implemented. The parameter 'path' is the path to a directory, 'id' is the request information object and the returned mapping contains all filenames in the directory mapped to Stat objects for the same files respectively.

If this method is not implemented, the find_dir_stat function inherited from module.pike maps the result of find_dir() over stat_file() to produce the same result. Providing your own find_dir_stat might be useful if your module maps its files from a database, in which case you would gain performance by using just one big query instead of hordes of single-file queries.

string|void real_file( string path, RequestID id )

This method translates the path of a file in the module's name space to the path to the file in the real file system. path is the path to the file in the module's name space, id is the request information object.

If the file could not be found, or the file does not exist on a real file system, zero should be returned. Only location modules that access server files from a real file system need implement this method. See also the stat_file() method.

array(string)|void find_dir( string path, RequestID id )

The find_dir() returns a directory listing; an array of strings containing the names of all files and directories in this directory. The path parameter is the path to the directory, in the module's name space, id is the request information object.

This method is usually called because a previous call to find_file() returned that this path contained a directory and a directory type module is right now trying to create a directory listing of this directory.

Note!

It is possible that the find_dir() is called in several location modules, and that the actual directory listing shown to the user will be the concatenated result of all those calls.

To find information about each entry in the returned array the stat_file() is used.