mod_mime_magic.html revision d030d579df50673f566f5dbcd1904fd59cd310e0
1ccbfca64ae86ace521053773001cb995352f96fBob Halley<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
1ccbfca64ae86ace521053773001cb995352f96fBob Halley BGCOLOR="#FFFFFF"
1ccbfca64ae86ace521053773001cb995352f96fBob Halley TEXT="#000000"
1ccbfca64ae86ace521053773001cb995352f96fBob Halley LINK="#0000FF"
1ccbfca64ae86ace521053773001cb995352f96fBob Halley VLINK="#000080"
1ccbfca64ae86ace521053773001cb995352f96fBob Halley ALINK="#FF0000"
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <IMG SRC="/images/sub.gif" ALT="[APACHE DOCUMENTATION]">
1ccbfca64ae86ace521053773001cb995352f96fBob Halley This module is contained in the mod_mime_magic.c file, and is
1ccbfca64ae86ace521053773001cb995352f96fBob Halley an optional extension to the Apache HTTPD server.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley It can be used to determine the MIME type of a file by looking at a
1ccbfca64ae86ace521053773001cb995352f96fBob Halley few bytes of its contents, the same way the Unix file(1) command works.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley To use mod_mime_magic you have to enable the following line in the
1ccbfca64ae86ace521053773001cb995352f96fBob Halley This should be listed <EM>before</EM> mod_mime in the build
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <TT>Configuration</TT> file so that it will be used after mod_mime.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley mod_mime_magic is intended as a "second line of defense" for cases
1ccbfca64ae86ace521053773001cb995352f96fBob Halley mod_mime cannot resolve.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley This module is derived from a free version of the <CODE>file(1)</CODE>
1ccbfca64ae86ace521053773001cb995352f96fBob Halley command for Unix,
1ccbfca64ae86ace521053773001cb995352f96fBob Halley which uses "magic numbers" and other hints from a file's contents to
1ccbfca64ae86ace521053773001cb995352f96fBob Halley figure out what the contents are.
4dfbac743493fc56a1ae391130b27f9517acb803Bob Halley In the case of this module,
4dfbac743493fc56a1ae391130b27f9517acb803Bob Halley it tries to figure out the MIME type of the file.
4dfbac743493fc56a1ae391130b27f9517acb803Bob Halley This module active only if the magic file is specified by the
4dfbac743493fc56a1ae391130b27f9517acb803Bob Halley <A HREF="#mimemagicfile"><CODE>MimeMagicFile</CODE></A> directive.
4dfbac743493fc56a1ae391130b27f9517acb803Bob Halley The contents of the file are plain ASCII text in 4-5 columns.
4dfbac743493fc56a1ae391130b27f9517acb803Bob Halley Blank lines are allowed but ignored.
e5c2e16bb21387962f0d04567d44d1a34cd83b4fBob Halley Commented lines use a hash mark "#".
4dfbac743493fc56a1ae391130b27f9517acb803Bob Halley The remaining lines are parsed for the following columns:
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <TD>byte number to begin checking from
1ccbfca64ae86ace521053773001cb995352f96fBob Halley ">" indicates a dependency upon the previous non-">" line</TD>
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <TD>type of data to match
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <TR><TD>short</TD><TD>machine-order 16-bit integer</TD></TR>
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <TR><TD>long</TD><TD>machine-order 32-bit integer</TD></TR>
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <TR><TD>string</TD><TD>arbitrary-length string</TD></TR>
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <TR><TD>beshort</TD><TD>big-endian 16-bit integer</TD></TR>
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <TR><TD>belong</TD><TD>big-endian 32-bit integer</TD></TR>
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <TR><TD>bedate</TD><TD>big-endian 32-bit integer date</TD></TR>
1ccbfca64ae86ace521053773001cb995352f96fBob Halley <TR><TD>leshort</TD><TD>little-endian 16-bit integer</TD></TR>
e5c2e16bb21387962f0d04567d44d1a34cd83b4fBob Halley <TR><TD>lelong</TD><TD>little-endian 32-bit integer</TD></TR>
e5c2e16bb21387962f0d04567d44d1a34cd83b4fBob Halley <TR><TD>ledate</TD><TD>little-endian 32-bit integer date</TD></TR>
1ccbfca64ae86ace521053773001cb995352f96fBob Halley For example, the following magic file lines
1ccbfca64ae86ace521053773001cb995352f96fBob Halley would recognize some audio formats.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley0 string .snd
4dfbac743493fc56a1ae391130b27f9517acb803Bob Halley Or these would recognize the difference between "*.doc" files containing
1ccbfca64ae86ace521053773001cb995352f96fBob Halley Microsoft Word or FrameMaker documents. (These are incompatible file
4dfbac743493fc56a1ae391130b27f9517acb803Bob Halley formats which use the same file suffix.)
1ccbfca64ae86ace521053773001cb995352f96fBob Halley0 string \320\317\021\340\241\261 application/msword
1ccbfca64ae86ace521053773001cb995352f96fBob Halley An optional MIME encoding can be included as a fifth column.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley For example, this can recognize gzipped files and set the encoding
1ccbfca64ae86ace521053773001cb995352f96fBob Halley# gzip (GNU zip, not to be confused with [Info-ZIP/PKWARE] zip archiver)
1ccbfca64ae86ace521053773001cb995352f96fBob Halley This module is not for every system. If your system is barely keeping
1ccbfca64ae86ace521053773001cb995352f96fBob Halley up with its load or if you're performing a web server benchmark,
1ccbfca64ae86ace521053773001cb995352f96fBob Halley you may not want to enable this because the processing is not free.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley However, an effort was made to improve the performance of the original
1ccbfca64ae86ace521053773001cb995352f96fBob Halley file(1) code to make it fit in a busy web server.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley It was designed for a server where there are thousands of users who
1ccbfca64ae86ace521053773001cb995352f96fBob Halley publish their own documents.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley This is probably very common on intranets.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley Many times, it's helpful
1ccbfca64ae86ace521053773001cb995352f96fBob Halley if the server can make more intelligent decisions about a file's
1ccbfca64ae86ace521053773001cb995352f96fBob Halley contents than the file name allows
1ccbfca64ae86ace521053773001cb995352f96fBob Halley ...even if just to reduce the "why doesn't my page work" calls
1ccbfca64ae86ace521053773001cb995352f96fBob Halley when users improperly name their own files.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley You have to decide if the extra work suits your environment.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley When compiling an Apache server, this module should be at or near the
1ccbfca64ae86ace521053773001cb995352f96fBob Halley top of the list of modules in the Configuration file. The modules are
1ccbfca64ae86ace521053773001cb995352f96fBob Halley listed in increasing priority so that will mean this one is used only
1ccbfca64ae86ace521053773001cb995352f96fBob Halley as a last resort, just like it was designed to.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley MimeMagicFile
1ccbfca64ae86ace521053773001cb995352f96fBob Halley ><STRONG>Syntax:</STRONG></A> MimeMagicFile <EM>magic-file-name</EM>
1ccbfca64ae86ace521053773001cb995352f96fBob Halley ><STRONG>Context:</STRONG></A> server config, virtual host
1ccbfca64ae86ace521053773001cb995352f96fBob Halley The <CODE>MimeMagicFile</CODE> directive can be used to enable this module,
1ccbfca64ae86ace521053773001cb995352f96fBob Halley the default file is distributed at <CODE>conf/magic</CODE>.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley Non-rooted paths are relative to the ServerRoot. Virtual hosts
1ccbfca64ae86ace521053773001cb995352f96fBob Halley will use the same file as the main server unless a more specific setting
1ccbfca64ae86ace521053773001cb995352f96fBob Halley is used, in which case the more specific setting overrides the main server's
1ccbfca64ae86ace521053773001cb995352f96fBob Halley The following notes apply to the mod_mime_magic module and are
1ccbfca64ae86ace521053773001cb995352f96fBob Halley included here for compliance with contributors' copyright restrictions
1ccbfca64ae86ace521053773001cb995352f96fBob Halley that require their acknowledgment.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * mod_mime_magic: MIME type lookup via file magic numbers
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * Copyright (c) 1996-1997 Cisco Systems, Inc.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * This software was submitted by Cisco Systems to the Apache Group in July
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * 1997. Future revisions and derivatives of this source code must
4dfbac743493fc56a1ae391130b27f9517acb803Bob Halley * acknowledge Cisco Systems as the original contributor of this module.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * All other licensing and usage conditions are those of the Apache Group.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * Some of this code is derived from the free version of the file command
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * originally posted to comp.sources.unix. Copyright info for that program
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * is included below as required.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * ---------------------------------------------------------------------------
e5c2e16bb21387962f0d04567d44d1a34cd83b4fBob Halley * - Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * This software is not subject to any license of the American Telephone and
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * Telegraph Company or of the Regents of the University of California.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * Permission is granted to anyone to use this software for any purpose on any
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * computer system, and to alter it and redistribute it freely, subject to
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * the following restrictions:
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * 1. The author is not responsible for the consequences of use of this
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * software, no matter how awful, even if they arise from flaws in it.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * 2. The origin of this software must not be misrepresented, either by
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * explicit claim or by omission. Since few users ever read sources, credits
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * must appear in the documentation.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * 3. Altered versions must be plainly marked as such, and must not be
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * misrepresented as being the original software. Since few users ever read
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * sources, credits must appear in the documentation.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * 4. This notice may not be removed or altered.
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * -------------------------------------------------------------------------
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * For compliance with Mr Darwin's terms: this has been very significantly
e5c2e16bb21387962f0d04567d44d1a34cd83b4fBob Halley * modified from the free "file" command.
e5c2e16bb21387962f0d04567d44d1a34cd83b4fBob Halley * - all-in-one file for compilation convenience when moving from one
e5c2e16bb21387962f0d04567d44d1a34cd83b4fBob Halley * version of Apache to the next.
e5c2e16bb21387962f0d04567d44d1a34cd83b4fBob Halley * - Memory allocation is done through the Apache API's pool structure.
e5c2e16bb21387962f0d04567d44d1a34cd83b4fBob Halley * - All functions have had necessary Apache API request or server
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * structures passed to them where necessary to call other Apache API
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * routines. (i.e. usually for logging, files, or memory allocation in
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * itself or a called function.)
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * - struct magic has been converted from an array to a single-ended linked
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * list because it only grows one record at a time, it's only accessed
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * sequentially, and the Apache API has no equivalent of realloc().
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * - Functions have been changed to get their parameters from the server
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * configuration instead of globals. (It should be reentrant now but has
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * not been tested in a threaded environment.)
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * - Places where it used to print results to stdout now saves them in a
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * list where they're used to set the MIME type in the Apache request
1ccbfca64ae86ace521053773001cb995352f96fBob Halley * - Command-line flags have been removed since they will never be used here.