.\"
.\" Copyright (c) Christos Zoulas 2003.
.\" All Rights Reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice immediately at the beginning of the file, without modification,
.\"    this list of conditions, and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR
.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" Japanese Version Copyright (c) 2003-2004 Yuichi SATO
.\"         all rights reserved.
.\" Translated Tue Jun  3 03:07:43 JST 2003
.\"         by Yuichi SATO <ysato444@yahoo.co.jp>
.\" Updated & Modified Sat Jan 31 21:47:17 JST 2004 by Yuichi SATO
.\"
.\"WORD:        
.\"
.Dd March 22, 2003
.Dt MAGIC 3
.Os
.Sh 名前
.Nm magic_open ,
.Nm magic_close ,
.Nm magic_error ,
.Nm magic_file ,
.Nm magic_buffer ,
.Nm magic_setflags ,
.Nm magic_check ,
.Nm magic_compile ,
.Nm magic_load
.Nd マジックナンバー識別ライブラリ
.Sh ライブラリ
.Lb libmagic
.Sh 書式
.In magic.h
.Ft magic_t
.Fn magic_open "int flags"
.Ft void
.Fn magic_close "magic_t cookie"
.Ft const char *
.Fn magic_error "magic_t cookie"
.Ft int
.Fn magic_errno "magic_t cookie"
.Ft const char *
.Fn magic_file "magic_t cookie, const char *filename"
.Ft const char *
.Fn magic_buffer "magic_t cookie, const void *buffer, size_t length"
.Ft int
.Fn magic_setflags "magic_t cookie, int flags"
.Ft int
.Fn magic_check "magic_t cookie, const char *filename"
.Ft int
.Fn magic_compile "magic_t cookie, const char *filename"
.Ft int
.Fn magic_load "magic_t cookie, const char *filename"
.Sh 説明
これらの関数は
.Xr magic 4
に記述されている magic データベースファイルを操作する。
.Pp
関数
.Fn magic_open
はマジッククッキーポインタを生成して返す。
マジッククッキーの割り当てにエラーがあった場合、
この関数は NULL を返す。
.Ar flags
引き数は、他のマジック関数の挙動を指定する。
.Bl -tag -width MAGIC_COMPRESS
.It Dv MAGIC_NONE
特別な処理を行わない。
.It Dv MAGIC_DEBUG
標準エラー出力にデバッグメッセージを表示する。
.It Dv MAGIC_SYMLINK
クエリしたファイルがシンボリックリンクであった場合は、それを辿る。
.It Dv MAGIC_COMPRESS
ファイルが圧縮されていた場合は、展開して内容を読み込む。
.It Dv MAGIC_DEVICES
ファイルがブロックスペシャルデバイスまたは
キャラクタスペシャルデバイスであった場合、
デバイスをオープンして内容を読み込もうとする。
.It Dv MAGIC_MIME
説明文ではなく mime 文字列を返す。
.It Dv MAGIC_CONTINUE
最初にマッチしたものだけではなく、マッチした全てを返す。
.It Dv MAGIC_CHECK
magic データベースの整合性をチェックし、
標準エラー出力に警告を表示する。
.It Dv MAGIC_PRESERVE_ATIME
.Xr utime 2
または
.Xr utimes 2
をサポートするシステムでは、
解析されたファイルのアクセス時刻を保存しようとする。
.It Dv MAGIC_RAW
印刷不能文字を \eooo のような 8 進数表現に変換しない。
.It Dv MAGIC_ERROR
ファイルやシンボリックリンクをオープンしようとしている間に
OS のエラーが起こった場合、
マジックバッファにエラーを表示せず、実際のエラーとして扱う。
.El
.Pp
.Fn magic_close
関数は
.Xr magic 4
データベースをクローズして、使用されている全てのリソースを解放する。
.Pp
.Fn magic_error
関数は最後に発生したエラーの説明文を返す。
エラーがない場合は NULL を返す。
.Pp
.Fn magic_errno
関数はシステムコールによって最後に発生した OS エラーの番号
.Xr ( errno 3 )
を返す。
.Pp
.Fn magic_file
関数は
.Ar filename
引き数で指定されたファイルの内容についての説明文を返す。
エラーが起った場合は NULL を返す。
.Ar filename
が NULL の場合は標準入力を使う。
.Pp
.Fn magic_buffer
関数はバイトサイズ
.Ar length
の引き数
.Ar buffer
の内容について、説明文を返す。
.Pp
.Fn magic_setflags
関数は上記の
.Ar flags
を設定する。
.Pp
.Fn magic_check
関数を使って、データベースファイルのエントリが有効であるかを検証できる。
検証されるデータベースは、コロン区切りのファイルリストの形式で、
.Ar filename
で指定される。
.Ar filename
が NULL の場合はデフォルトのデータベースを検証する。
検証が成功した場合は 0 を返し、
失敗した場合は -1 を返す。
.Pp
.Fn magic_compile
関数を使って、データベースをコンパイルできる。
コンパイルされるデータベースは、コロン区切りのファイルリストの形式で、
.Ar filename
で指定される。
.Ar filename
が NULL の場合は、デフォルトのデータベースがコンパイルされる。
コンパイルが成功した場合は 0 を返し、
失敗した場合は -1 を返す。
コンパイルして生成されたファイルの名前は、
各ファイル引き数に
.Xr basename 1
を適用して ".mgc" を追加したものになる。
.Pp
何かマジッククエリを実行する前には、
.Fn magic_load
関数を使ってデータベースファイルをロードしなければならない。
ロードするデータベースは、コロン区切りのファイルリストの形式で、
.Ar filename
で指定される。
.Ar filename
が NULL の場合は、デフォルトのデータベースがロードされる。
.Pp
デフォルトのデータベースファイルは、
環境変数 MAGIC によって名前が指定される。
この環境変数が設定されない場合、
デフォルトのデータベースファイル名は /usr/share/file/magic である。
.Pp
.Fn magic_load
データベースファイル名に ".mime" と ".mgc" を適宜追加する
(どちらか一方の場合もある)。
.Sh 返り値
関数
.Fn magic_open
が成功した場合はマジッククッキーが返される。
失敗した場合は NULL が返されて、
errno が適切な値に設定される。
サポートされていない値がフラグに指定された場合、
errno が EINVAL に設定される。
.Fn magic_load ,
.Fn magic_compile ,
.Fn magic_check
関数が成功した場合は 0 が返され、失敗した場合は -1 が返される。
.Fn magic_file ,
.Fn magic_buffer 
関数が成功した場合は文字列が返され、失敗した場合は NULL が返される。
.Fn magic_error
関数は上記の関数のエラーの説明文を返す。
エラーがない場合は NULL を返す。
そして、
.Xr utime 2
または
.Xr utimes 2
がサポートされていないシステムで
.Dv MAGIC_PRESERVE_ATIME
が設定されると、
.Fn magic_setflags
は -1 を返す。
.Sh ファイル
.Bl -tag -width /usr/share/file/magic.mime.mgc -compact
.It Pa /usr/share/file/magic.mime
コンパイルされていないデフォルトの magic mime データベース。
.It Pa /usr/share/file/magic.mime.mgc
コンパイル済みのデフォルトの magic mime データベース。
.It Pa /usr/share/file/magic
コンパイルされていないデフォルトの magic データベース。
.It Pa /usr/share/file/magic.mgc
コンパイル済みのデフォルトの magic データベース。
.El
.Sh 関連項目
.Xr file 1 ,
.Xr magic 4 
.Sh 著者
Mans Rullgard が最初の libmagic の実装と構成を行った。
Christos Zoulas は API を整理し、
エラーコードと (マジッククッキーの) 割り当てを実装した。