libmagic.man 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387
  1. .\" $File: libmagic.man,v 1.37 2015/06/03 18:21:24 christos Exp $
  2. .\"
  3. .\" Copyright (c) Christos Zoulas 2003.
  4. .\" All Rights Reserved.
  5. .\"
  6. .\" Redistribution and use in source and binary forms, with or without
  7. .\" modification, are permitted provided that the following conditions
  8. .\" are met:
  9. .\" 1. Redistributions of source code must retain the above copyright
  10. .\" notice immediately at the beginning of the file, without modification,
  11. .\" this list of conditions, and the following disclaimer.
  12. .\" 2. Redistributions in binary form must reproduce the above copyright
  13. .\" notice, this list of conditions and the following disclaimer in the
  14. .\" documentation and/or other materials provided with the distribution.
  15. .\"
  16. .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
  20. .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26. .\" SUCH DAMAGE.
  27. .\"
  28. .Dd June 3, 2015
  29. .Dt LIBMAGIC 3
  30. .Os
  31. .Sh NAME
  32. .Nm magic_open ,
  33. .Nm magic_close ,
  34. .Nm magic_error ,
  35. .Nm magic_errno ,
  36. .Nm magic_descriptor ,
  37. .Nm magic_buffer ,
  38. .Nm magic_setflags ,
  39. .Nm magic_check ,
  40. .Nm magic_compile ,
  41. .Nm magic_list ,
  42. .Nm magic_load ,
  43. .Nm magic_load_buffers ,
  44. .Nm magic_setparam ,
  45. .Nm magic_getparam ,
  46. .Nm magic_version
  47. .Nd Magic number recognition library
  48. .Sh LIBRARY
  49. .Lb libmagic
  50. .Sh SYNOPSIS
  51. .In magic.h
  52. .Ft magic_t
  53. .Fn magic_open "int flags"
  54. .Ft void
  55. .Fn magic_close "magic_t cookie"
  56. .Ft const char *
  57. .Fn magic_error "magic_t cookie"
  58. .Ft int
  59. .Fn magic_errno "magic_t cookie"
  60. .Ft const char *
  61. .Fn magic_descriptor "magic_t cookie" "int fd"
  62. .Ft const char *
  63. .Fn magic_file "magic_t cookie" "const char *filename"
  64. .Ft const char *
  65. .Fn magic_buffer "magic_t cookie" "const void *buffer" "size_t length"
  66. .Ft int
  67. .Fn magic_setflags "magic_t cookie" "int flags"
  68. .Ft int
  69. .Fn magic_check "magic_t cookie" "const char *filename"
  70. .Ft int
  71. .Fn magic_compile "magic_t cookie" "const char *filename"
  72. .Ft int
  73. .Fn magic_list "magic_t cookie" "const char *filename"
  74. .Ft int
  75. .Fn magic_load "magic_t cookie" "const char *filename"
  76. .Ft int
  77. .Fn magic_load_buffers "magic_t cookie" "void **buffers" "size_t *sizes" "size_t nbuffers"
  78. .Ft int
  79. .Fn magic_getparam "magic_t cookie" "int param" "void *value"
  80. .Ft int
  81. .Fn magic_setparam "magic_t cookie" "int param" "const void *value"
  82. .Ft int
  83. .Fn magic_version "void"
  84. .Sh DESCRIPTION
  85. These functions
  86. operate on the magic database file
  87. which is described
  88. in
  89. .Xr magic __FSECTION__ .
  90. .Pp
  91. The function
  92. .Fn magic_open
  93. creates a magic cookie pointer and returns it.
  94. It returns
  95. .Dv NULL
  96. if there was an error allocating the magic cookie.
  97. The
  98. .Ar flags
  99. argument specifies how the other magic functions should behave:
  100. .Bl -tag -width MAGIC_COMPRESS
  101. .It Dv MAGIC_NONE
  102. No special handling.
  103. .It Dv MAGIC_DEBUG
  104. Print debugging messages to stderr.
  105. .It Dv MAGIC_SYMLINK
  106. If the file queried is a symlink, follow it.
  107. .It Dv MAGIC_COMPRESS
  108. If the file is compressed, unpack it and look at the contents.
  109. .It Dv MAGIC_DEVICES
  110. If the file is a block or character special device, then open the device
  111. and try to look in its contents.
  112. .It Dv MAGIC_MIME_TYPE
  113. Return a MIME type string, instead of a textual description.
  114. .It Dv MAGIC_MIME_ENCODING
  115. Return a MIME encoding, instead of a textual description.
  116. .It Dv MAGIC_MIME
  117. A shorthand for MAGIC_MIME_TYPE | MAGIC_MIME_ENCODING.
  118. .It Dv MAGIC_CONTINUE
  119. Return all matches, not just the first.
  120. .It Dv MAGIC_CHECK
  121. Check the magic database for consistency and print warnings to stderr.
  122. .It Dv MAGIC_PRESERVE_ATIME
  123. On systems that support
  124. .Xr utime 3
  125. or
  126. .Xr utimes 2 ,
  127. attempt to preserve the access time of files analysed.
  128. .It Dv MAGIC_RAW
  129. Don't translate unprintable characters to a \eooo octal representation.
  130. .It Dv MAGIC_ERROR
  131. Treat operating system errors while trying to open files and follow symlinks
  132. as real errors, instead of printing them in the magic buffer.
  133. .It Dv MAGIC_APPLE
  134. Return the Apple creator and type.
  135. .It Dv MAGIC_EXTENSION
  136. Return a slash-separated list of extensions for this file type.
  137. .It Dv MAGIC_COMPRESS_TRANSP
  138. Don't report on compression, only report about the uncompressed data.
  139. .It Dv MAGIC_NO_CHECK_APPTYPE
  140. Don't check for
  141. .Dv EMX
  142. application type (only on EMX).
  143. .It Dv MAGIC_NO_CHECK_CDF
  144. Don't get extra information on MS Composite Document Files.
  145. .It Dv MAGIC_NO_CHECK_COMPRESS
  146. Don't look inside compressed files.
  147. .It Dv MAGIC_NO_CHECK_ELF
  148. Don't print ELF details.
  149. .It Dv MAGIC_NO_CHECK_ENCODING
  150. Don't check text encodings.
  151. .It Dv MAGIC_NO_CHECK_SOFT
  152. Don't consult magic files.
  153. .It Dv MAGIC_NO_CHECK_TAR
  154. Don't examine tar files.
  155. .It Dv MAGIC_NO_CHECK_TEXT
  156. Don't check for various types of text files.
  157. .It Dv MAGIC_NO_CHECK_TOKENS
  158. Don't look for known tokens inside ascii files.
  159. .El
  160. .Pp
  161. The
  162. .Fn magic_close
  163. function closes the
  164. .Xr magic __FSECTION__
  165. database and deallocates any resources used.
  166. .Pp
  167. The
  168. .Fn magic_error
  169. function returns a textual explanation of the last error, or
  170. .Dv NULL
  171. if there was no error.
  172. .Pp
  173. The
  174. .Fn magic_errno
  175. function returns the last operating system error number
  176. .Pq Xr errno 2
  177. that was encountered by a system call.
  178. .Pp
  179. The
  180. .Fn magic_file
  181. function returns a textual description of the contents of the
  182. .Ar filename
  183. argument, or
  184. .Dv NULL
  185. if an error occurred.
  186. If the
  187. .Ar filename
  188. is
  189. .Dv NULL ,
  190. then stdin is used.
  191. .Pp
  192. The
  193. .Fn magic_descriptor
  194. function returns a textual description of the contents of the
  195. .Ar fd
  196. argument, or
  197. .Dv NULL
  198. if an error occurred.
  199. .Pp
  200. The
  201. .Fn magic_buffer
  202. function returns a textual description of the contents of the
  203. .Ar buffer
  204. argument with
  205. .Ar length
  206. bytes size.
  207. .Pp
  208. The
  209. .Fn magic_setflags
  210. function sets the
  211. .Ar flags
  212. described above.
  213. Note that using both MIME flags together can also
  214. return extra information on the charset.
  215. .Pp
  216. The
  217. .Fn magic_check
  218. function can be used to check the validity of entries in the colon
  219. separated database files passed in as
  220. .Ar filename ,
  221. or
  222. .Dv NULL
  223. for the default database.
  224. It returns 0 on success and \-1 on failure.
  225. .Pp
  226. The
  227. .Fn magic_compile
  228. function can be used to compile the the colon
  229. separated list of database files passed in as
  230. .Ar filename ,
  231. or
  232. .Dv NULL
  233. for the default database.
  234. It returns 0 on success and \-1 on failure.
  235. The compiled files created are named from the
  236. .Xr basename 1
  237. of each file argument with
  238. .Dq .mgc
  239. appended to it.
  240. .Pp
  241. The
  242. .Fn magic_list
  243. function dumps all magic entries in a human readable format,
  244. dumping first the entries that are matched against binary files and then the
  245. ones that match text files.
  246. It takes and optional
  247. .Fa filename
  248. argument which is a colon separated list of database files, or
  249. .Dv NULL
  250. for the default database.
  251. .Pp
  252. The
  253. .Fn magic_load
  254. function must be used to load the the colon
  255. separated list of database files passed in as
  256. .Ar filename ,
  257. or
  258. .Dv NULL
  259. for the default database file before any magic queries can performed.
  260. .Pp
  261. The default database file is named by the MAGIC environment variable.
  262. If that variable is not set, the default database file name is __MAGIC__.
  263. .Fn magic_load
  264. adds
  265. .Dq .mgc
  266. to the database filename as appropriate.
  267. .Pp
  268. The
  269. .Fn magic_load_buffers
  270. function takes an array of size
  271. .Fa nbuffers
  272. of
  273. .Fa buffers
  274. with a respective size for each in the array of
  275. .Fa sizes
  276. loaded with the contents of the magic databases from the filesystem.
  277. This function can be used in environment where the magic library does
  278. not have direct access to the filesystem, but can access the magic
  279. database via shared memory or other IPC means.
  280. .Pp
  281. The
  282. .Fn magic_getparam
  283. and
  284. .Fn magic_setparam
  285. allow getting and setting various limits related to the the magic
  286. library.
  287. .Bl -column "MAGIC_PARAM_ELF_PHNUM_MAX" "size_t" "Default" -offset indent
  288. .It Sy "Parameter" Ta Sy "Type" Ta Sy "Default"
  289. .It Li MAGIC_PARAM_INDIR_MAX Ta size_t Ta 15
  290. .It Li MAGIC_PARAM_NAME_MAX Ta size_t Ta 30
  291. .It Li MAGIC_PARAM_ELF_NOTES_MAX Ta size_t Ta 256
  292. .It Li MAGIC_PARAM_ELF_PHNUM_MAX Ta size_t Ta 128
  293. .It Li MAGIC_PARAM_ELF_SHNUM_MAX Ta size_t Ta 32768
  294. .El
  295. .Pp
  296. The
  297. .Dv MAGIC_PARAM_INDIR_RECURSION
  298. parameter controls how many levels of recursion will be followed for
  299. indirect magic entries.
  300. .Pp
  301. The
  302. .Dv MAGIC_PARAM_NAME_RECURSION
  303. parameter controls how many levels of recursion will be followed for
  304. for name/use calls.
  305. .Pp
  306. The
  307. .Dv MAGIC_PARAM_NAME_MAX
  308. parameter controls the maximum number of calls for name/use.
  309. .Pp
  310. The
  311. .Dv MAGIC_PARAM_NOTES_MAX
  312. parameter controls how many ELF notes will be processed.
  313. .Pp
  314. The
  315. .Dv MAGIC_PARAM_PHNUM_MAX
  316. parameter controls how many ELF program sections will be processed.
  317. .Pp
  318. The
  319. .Dv MAGIC_PARAM_SHNUM_MAX
  320. parameter controls how many ELF sections will be processed.
  321. .Pp
  322. The
  323. .Fn magic_version
  324. command returns the version number of this library which is compiled into
  325. the shared library using the constant
  326. .Dv MAGIC_VERSION
  327. from
  328. .In magic.h .
  329. This can be used by client programs to verify that the version they compile
  330. against is the same as the version that they run against.
  331. .Sh RETURN VALUES
  332. The function
  333. .Fn magic_open
  334. returns a magic cookie on success and
  335. .Dv NULL
  336. on failure setting errno to an appropriate value.
  337. It will set errno to
  338. .Er EINVAL
  339. if an unsupported value for flags was given.
  340. The
  341. .Fn magic_list ,
  342. .Fn magic_load ,
  343. .Fn magic_compile ,
  344. and
  345. .Fn magic_check
  346. functions return 0 on success and \-1 on failure.
  347. The
  348. .Fn magic_buffer ,
  349. .Fn magic_getpath ,
  350. and
  351. .Fn magic_file ,
  352. functions return a string on success and
  353. .Dv NULL
  354. on failure.
  355. The
  356. .Fn magic_error
  357. function returns a textual description of the errors of the above
  358. functions, or
  359. .Dv NULL
  360. if there was no error.
  361. The
  362. .Fn magic_version
  363. always returns the version number of the library.
  364. Finally,
  365. .Fn magic_setflags
  366. returns \-1 on systems that don't support
  367. .Xr utime 3 ,
  368. or
  369. .Xr utimes 2
  370. when
  371. .Dv MAGIC_PRESERVE_ATIME
  372. is set.
  373. .Sh FILES
  374. .Bl -tag -width __MAGIC__.mgc -compact
  375. .It Pa __MAGIC__
  376. The non-compiled default magic database.
  377. .It Pa __MAGIC__.mgc
  378. The compiled default magic database.
  379. .El
  380. .Sh SEE ALSO
  381. .Xr file __CSECTION__ ,
  382. .Xr magic __FSECTION__
  383. .Sh AUTHORS
  384. .An M\(oans Rullg\(oard
  385. Initial libmagic implementation, and configuration.
  386. .An Christos Zoulas
  387. API cleanup, error code and allocation handling.