granicus.if.org Git - apache/blob - docs/manual/mod/mod_mime_magic.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_mime_magic - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16 <p class="apache">Apache HTTP Server Version 2.3</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_mime_magic</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_mime_magic.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Determines the MIME type of a file
  27     by looking at a few bytes of its contents</td></tr>
  28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>mime_magic_module</td></tr>
  30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_mime_magic.c</td></tr></table>
  31 <h3>Summary</h3>
  32
  33     <p>This module determines the <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME
  34     type</a> of files in the same way the Unix
  35     <code>file(1)</code> command works: it looks at the first few
  36     bytes of the file. It is intended as a "second line of defense"
  37     for cases that <code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code> can't resolve.</p>
  38
  39     <p>This module is derived from a free version of the
  40     <code>file(1)</code> command for Unix, which uses "magic
  41     numbers" and other hints from a file's contents to figure out
  42     what the contents are. This module is active only if the magic
  43     file is specified by the <code class="directive"><a href="#mimemagicfile">MimeMagicFile</a></code> directive.</p>
  44 </div>
  45 <div id="quickview"><h3 class="directives">Directives</h3>
  46 <ul id="toc">
  47 <li><img alt="" src="../images/down.gif" /> <a href="#mimemagicfile">MimeMagicFile</a></li>
  48 </ul>
  49 <h3>Topics</h3>
  50 <ul id="topics">
  51 <li><img alt="" src="../images/down.gif" /> <a href="#format">Format of the Magic File</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#performance">Performance Issues</a></li>
  53 <li><img alt="" src="../images/down.gif" /> <a href="#notes">Notes</a></li>
  54 </ul></div>
  55 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  56 <div class="section">
  57 <h2><a name="format" id="format">Format of the Magic File</a></h2>
  58
  59     <p>The contents of the file are plain ASCII text in 4-5
  60     columns. Blank lines are allowed but ignored. Commented lines
  61     use a hash mark (<code>#</code>). The remaining lines are parsed for
  62     the following columns:</p>
  63
  64     <table class="bordered"><tr class="header"><th>Column</th><th>Description</th></tr>
  65 <tr><td>1</td>
  66         <td>byte number to begin checking from<br />
  67          "<code>&gt;</code>" indicates a dependency upon the previous
  68          non-"<code>&gt;</code>" line</td></tr>
  69 <tr class="odd"><td>2</td>
  70         <td><p>type of data to match</p>
  71         <table class="bordered">
  72
  73         <tr><td><code>byte</code></td>
  74             <td>single character</td></tr>
  75         <tr><td><code>short</code></td>
  76             <td>machine-order 16-bit integer</td></tr>
  77         <tr><td><code>long</code></td>
  78             <td>machine-order 32-bit integer</td></tr>
  79         <tr><td><code>string</code></td>
  80             <td>arbitrary-length string</td></tr>
  81         <tr><td><code>date</code></td>
  82             <td>long integer date (seconds since Unix epoch/1970)</td></tr>
  83         <tr><td><code>beshort</code></td>
  84             <td>big-endian 16-bit integer</td></tr>
  85         <tr><td><code>belong</code></td>
  86             <td>big-endian 32-bit integer</td></tr>
  87         <tr><td><code>bedate</code></td>
  88             <td>big-endian 32-bit integer date</td></tr>
  89         <tr><td><code>leshort</code></td>
  90             <td>little-endian 16-bit integer</td></tr>
  91         <tr><td><code>lelong</code></td>
  92             <td>little-endian 32-bit integer</td></tr>
  93         <tr><td><code>ledate</code></td>
  94             <td>little-endian 32-bit integer date</td></tr>
  95         </table></td></tr>
  96 <tr><td>3</td>
  97         <td>contents of data to match</td></tr>
  98 <tr class="odd"><td>4</td>
  99         <td>MIME type if matched</td></tr>
 100 <tr><td>5</td>
 101         <td>MIME encoding if matched (optional)</td></tr>
 102 </table>
 103
 104     <p>For example, the following magic file lines would recognize
 105     some audio formats:</p>
 106
 107     <div class="example"><pre># Sun/NeXT audio data
 108 0      string      .snd
 109 &gt;12    belong      1       audio/basic
 110 &gt;12    belong      2       audio/basic
 111 &gt;12    belong      3       audio/basic
 112 &gt;12    belong      4       audio/basic
 113 &gt;12    belong      5       audio/basic
 114 &gt;12    belong      6       audio/basic
 115 &gt;12    belong      7       audio/basic
 116 &gt;12    belong     23       audio/x-adpcm</pre></div>
 117
 118     <p>Or these would recognize the difference between <code>*.doc</code>
 119     files containing Microsoft Word or FrameMaker documents. (These are
 120     incompatible file formats which use the same file suffix.)</p>
 121
 122     <div class="example"><pre># Frame
 123 0  string  \&lt;MakerFile        application/x-frame
 124 0  string  \&lt;MIFFile          application/x-frame
 125 0  string  \&lt;MakerDictionary  application/x-frame
 126 0  string  \&lt;MakerScreenFon   application/x-frame
 127 0  string  \&lt;MML              application/x-frame
 128 0  string  \&lt;Book             application/x-frame
 129 0  string  \&lt;Maker            application/x-frame
 130
 131 # MS-Word
 132 0  string  \376\067\0\043            application/msword
 133 0  string  \320\317\021\340\241\261  application/msword
 134 0  string  \333\245-\0\0\0           application/msword</pre></div>
 135
 136     <p>An optional MIME encoding can be included as a fifth column.
 137     For example, this can recognize gzipped files and set the
 138     encoding for them.</p>
 139
 140     <div class="example"><pre># gzip (GNU zip, not to be confused with
 141 #       [Info-ZIP/PKWARE] zip archiver)
 142
 143 0  string  \037\213  application/octet-stream  x-gzip</pre></div>
 144 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 145 <div class="section">
 146 <h2><a name="performance" id="performance">Performance Issues</a></h2>
 147     <p>This module is not for every system. If your system is barely
 148     keeping up with its load or if you're performing a web server
 149     benchmark, you may not want to enable this because the
 150     processing is not free.</p>
 151
 152     <p>However, an effort was made to improve the performance of
 153     the original <code>file(1)</code> code to make it fit in a busy web
 154     server. It was designed for a server where there are thousands of users
 155     who publish their own documents. This is probably very common
 156     on intranets. Many times, it's helpful if the server can make
 157     more intelligent decisions about a file's contents than the
 158     file name allows ...even if just to reduce the "why doesn't my
 159     page work" calls when users improperly name their own files.
 160     You have to decide if the extra work suits your
 161     environment.</p>
 162 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 163 <div class="section">
 164 <h2><a name="notes" id="notes">Notes</a></h2>
 165     <p>The following notes apply to the <code class="module"><a href="../mod/mod_mime_magic.html">mod_mime_magic</a></code>
 166     module and are included here for compliance with contributors'
 167     copyright restrictions that require their acknowledgment.</p>
 168
 169     <div class="note">
 170       <p>mod_mime_magic: MIME type lookup via file magic numbers<br />
 171       Copyright (c) 1996-1997 Cisco Systems, Inc.</p>
 172
 173       <p>This software was submitted by Cisco Systems to the Apache Group
 174       in July 1997. Future revisions and derivatives of this source code
 175       must acknowledge Cisco Systems as the original contributor of this
 176       module. All other licensing and usage conditions are those of the
 177       Apache Group.</p>
 178
 179       <p>Some of this code is derived from the free version of the file
 180       command originally posted to comp.sources.unix. Copyright info for
 181       that program is included below as required.</p>
 182     </div>
 183
 184     <div class="note">
 185       <p> - Copyright (c) Ian F. Darwin, 1987. Written by Ian F. Darwin.</p>
 186
 187       <p>This software is not subject to any license of the American
 188       Telephone and Telegraph Company or of the Regents of the University
 189       of California.</p>
 190
 191       <p>Permission is granted to anyone to use this software for any
 192       purpose on any computer system, and to alter it and redistribute it
 193       freely, subject to the following restrictions:</p>
 194
 195       <ol>
 196         <li>The author is not responsible for the consequences of use of
 197         this software, no matter how awful, even if they arise from flaws
 198         in it.</li>
 199
 200         <li>The origin of this software must not be misrepresented, either
 201         by explicit claim or by omission. Since few users ever read
 202         sources, credits must appear in the documentation.</li>
 203
 204         <li>Altered versions must be plainly marked as such, and must not
 205         be misrepresented as being the original software. Since few users
 206         ever read sources, credits must appear in the documentation.</li>
 207
 208         <li>This notice may not be removed or altered.</li>
 209       </ol>
 210     </div>
 211
 212     <div class="note">
 213       <p>For compliance with Mr Darwin's terms: this has been very
 214       significantly modified from the free "file" command.</p>
 215
 216       <ul>
 217         <li>all-in-one file for compilation convenience when moving from
 218         one version of Apache to the next.</li>
 219
 220         <li>Memory allocation is done through the Apache API's pool
 221         structure.</li>
 222
 223         <li>All functions have had necessary Apache API request or server
 224         structures passed to them where necessary to call other Apache API
 225         routines. (<em>i.e.</em>, usually for logging, files, or memory
 226         allocation in itself or a called function.)</li>
 227
 228         <li>struct magic has been converted from an array to a single-ended
 229         linked list because it only grows one record at a time, it's only
 230         accessed sequentially, and the Apache API has no equivalent of
 231         <code>realloc()</code>.</li>
 232
 233         <li>Functions have been changed to get their parameters from the
 234         server configuration instead of globals.  (It should be reentrant
 235         now but has not been tested in a threaded environment.)</li>
 236
 237         <li>Places where it used to print results to stdout now saves them
 238         in a list where they're used to set the MIME type in the Apache
 239         request record.</li>
 240
 241         <li>Command-line flags have been removed since they will never be
 242         used here.</li>
 243       </ul>
 244     </div>
 245 </div>
 246 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 247 <div class="directive-section"><h2><a name="MimeMagicFile" id="MimeMagicFile">MimeMagicFile</a> <a name="mimemagicfile" id="mimemagicfile">Directive</a></h2>
 248 <table class="directive">
 249 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable MIME-type determination based on file contents
 250 using the specified magic file</td></tr>
 251 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>MimeMagicFile <var>file-path</var></code></td></tr>
 252 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 253 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 254 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_mime_magic</td></tr>
 255 </table>
 256     <p>The <code class="directive">MimeMagicFile</code> directive can be used to
 257     enable this module, the default file is distributed at
 258     <code>conf/magic</code>. Non-rooted paths are relative to the
 259     <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code>. Virtual hosts will use
 260     the same file as the main server unless a more specific setting is
 261     used, in which case the more specific setting overrides the main
 262     server's file.</p>
 263
 264     <div class="example"><h3>Example</h3><p><code>
 265       MimeMagicFile conf/magic
 266     </code></p></div>
 267
 268 </div>
 269 </div>
 270 <div class="bottomlang">
 271 <p><span>Available Languages: </span><a href="../en/mod/mod_mime_magic.html" title="English">&nbsp;en&nbsp;</a></p>
 272 </div><div id="footer">
 273 <p class="apache">Copyright 2011 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 274 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 275 </body></html>