Plexus Support Routines

plexus

&process_request

This is the entry point for th child process. I/O is from STDIN/STDOUT, and it inherits %in_headers and %out_headers from the parent.

&bind_port($FH, $port, $proto)

$FH is the filehandle to connect the socket to, $port is the port number, and $proto is the symbolic protocol to use (e.g., tcp or udp). You can add additional services into the plexus from the local.conf file by simply having your service bind to a port with &bind_port and then registering the socket in the @sockets array. For example: &bind_port(local_serv_fh, 8001, tcp); push(@sockets, local_serv_fh);. You can also configure your local &net_filter to detect which port a connection was made on since it is passed the filehandle as its first argument.

&error($status, $msg)

Where $status is defined in the config file by %code. $msg is an arbitrary message to be included in the output.

&debug($msg)

&debug writes $msg to STDOUT when the debug option (-D) is enabled.

&hostname($ipaddress)

&hostname returns either the fully qualified domain name or a dot quad ip address from the given $ipaddress.

&open($FH, $file)

&open trys to locate $file by searching @INC. Attaches the open file to the specified filehandle or returns undef.

&set_timeout

Set the alarm().

&clear_timeout;

Clear the alarm().

$pstring = &printable($string);

Converts non-printable characters in $string to their $## form.

@fields = &splitquery($query);

Splits the query on ``+'' characters then converts %## strings to thier character form.

&safeopen($fh, $file);

Opens a $file that may contain unsafe data (pipe characters, 8-bit data, etc). Works just like normal open except you have to pass in the package name (e.g., &main'safeopen("mypackage'FH", $file) || &main'error('bad_request', "$file: $!");.

get.pl

&do_get($request, $version)

The &do_get routine handles mappings between the URL path and the actual data. For most documents the two will be the same but you can interpose translators using the %map associative array to specify alternate routines for handling the request. The default is $map{'__default__'} and as distributed is set to &retrieve. The mappings can be customized in the config file.

dir.pl

&retrieve($path, $filter)

Decides if the requested path is a file or directory and calls either &wrap_file or &index_dir to handle it. If it's a file &retrieve first calls &deduce_content to decide what kind of file it is.

&deduce_content($path)

Recursively looks up the file extension in %encoding and %ext to determine the file content and encoding. If unknown it uses the perl -B test to decide if it a binary file, if so it returns $content_binary; if not it returns $content_plain.

&wrap_file($path)

Sends the specified file wrapped with an appropriate MIME header as to the deduced Content-type. Also, handles doing any translations that are needed to get the file to an acceptable format. This part will probably change again in the future when translations are done better. See setext.pl for an example translator.

To send raw data use &raw_file.

&raw_file($path)

Sends the data from the specified file out the socket. This is used for internal routines that need to combine several files into one document. They are responsible for sending the MIME headers.

&wrap_fd($FD, $content)

Sends a MIME header for type $content and then sends the data from $FD.

&raw_fd($FROM, $TO)

Reads from $FROM and writes to $TO. No translation.

&index_dir($dir, $filter)

Generates a listing for the files and directories in the specified path. If present, $dir_header is sent before the listing and $dir_footer is sent after the listing. There are default headers and footers provided if the files are not present. The listing includes the last modification time, size, and a directory/file indicator.

decode.pl

&loadmask(*image)

Loads the data pointed to by $image{'filename'} into $image{'bits'} for use by &pixel. The $image{'width'} and $image{'height'} elements must be set before the call. The element $image{'scanlen'} is also returned.

&pixel(*image, $x, $y)

Returns the bit at $x,$y in %image. Must have been already been loaded by &loadmask or equivalent.

&region($file, $width, $height, $x, $y)

Loads the image pointed to by $file and returns the pixel value at $x,$y. The data from $file is cached for performance.

grep.pl

&grep($matched, $flags, $pat, *FH)

Iterates over the data stream FH looking for $pat. On matches (inverted by the v flag) it calls the routine pointed to by $matched which has access to $_. If $matched returns true the grep is halted at the current point in the input stream. The $flags available are:

i

Ignore case in pattern match.

v

Reverse the sense of the pattern test (match lines not containing $pat).

p

Paragraph mode ($_ contains the surrounding paragraph if any line matches).

mime.pl

&MIME_header($status, $content)

Outputs the MIME headers required for HTTP/1.0. In addition to the standard headers (Date, Server, MIME-version, Content-type) any additional headers in %out_headers are output (Last-Modified and Content-encoding are the most common ones).

&fmt_date($time)

Returns a MIME compliant formatted date string given $time in seconds since the epoch.

&parse_headers(*headers)

Reads from <NS> and processes RFC822 mail headers into an internal format in %headers.

&add_header(*headers, $header_string)

Parses $header_string into the internal header format stored in %headers. This is mostly used for adding headers to %out_headers that is used by &MIME_headers.

&unparse_headers(*headers)

Outputs RFC822 compliant headers from the internal format in %headers.

site.pl

&seize($FH, $operation)

&seize applies or removes an advisory lock on the file associated with the file descriptor $FH. Seize can be configured to use either flock() or fcntl() style locking in your local.conf file. A lock is applied by specifying a $operation parameter that is the inclusive or of &LOCK_SH or &LOCK_EX and, possibly, &LOCK_NB. To unlock an existing lock operation it should be &LOCK_UN.

&LOCK_SH

Shared lock (for reading)

&LOCK_EX

Exclusive lock (for writing)

&LOCK_NB

Don't block when locking

&LOCK_UN

Unlock (happens automatically on close)

Sets or clears the &F_SETFD flags on the associated filehandles.