.\" $NetBSD$
.\"
.\" Copyright (c)2009 Citrus Project,
.\" 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, 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.
.\"
.Dd Septemper 29, 2009
.Dt CITRUS_MODULE 3
.Os
.\" ----------------------------------------------------------------------
.Sh NAME
.Nm _citrus_module_t ,
.Nm _citrus_load_module ,
.Nm _citrus_find_getopts ,
.Nm _citrus_unload_modle
.Nd プラグインモジュール操作インタフェース
.\" ----------------------------------------------------------------------
.Sh SYNOPSIS
.Fd #include "citrus_module.h"
.Ft int
.Fn _citrus_load_module "_citrus_module_t * resrict pmodule" "const char * restrict modname"
.Ft void *
.Fn _citrus_find_getops "_citrus_module_t module" "const char * restrict namespace" "const char * restrict ifname"
.Ft void
.Fn _citrus_unload_module "_citrus_module_t module"
.\" ----------------------------------------------------------------------
.Sh DESCRIPTION
.Ft _citrus_module_t
型はプラグインモジュールのハンドラで, 実装依存の不透明オブジェクトです。
.Pp
.Fn _citrus_load_module
関数は
.Fa modname
で指定された名前のプラグインモジュールをロードし, 成功した場合はハンドラを
.Fa *pmodname
に保存します。
.Fa pmodule
および
.Fa modname
が
.Dv NULL
の場合, 動作は未定義です。
.Pp
.Fn _citrus_find_getops
関数は
.Fa module
で渡されたハンドラから
.Fa namespace
および
.Fa ifname
で指定されたインタフェースを検索します。
.Fa module
が
.Dv NULL
あるいは無効な値の場合, また
.Fa namespace
および
.Fa ifname
が
.Dv NULL
の場合, 動作は未定義です。
.Pp
.Fn _citrus_unload_module
関数はハンドラに関連付いたプラグインモジュールをアンロードします。
.Fa module
が
.Dv NULL
あるいは無効な値の場合, 動作は未定義です。
.Pp
.\" ----------------------------------------------------------------------
.Sh RETURN VALUE
.Fn _citrus_load_module
は成功した場合は0, 失敗した場合は実装依存のエラーコードを返します。
.Pp
.Fn _citrus_find_getops
は成功した場合はインタフェースのアドレスを, 失敗した場合は
.Dv NULL
を返します。
.Sh IMPLEMENTATION
現在のNetBSDでは, プラグインモジュール形式は動的共有ライブラリそのものであり
.Fn _citrus_load_module
は
.Xr dlopen 3 ,
.Fn _citrus_find_getops
は
.Xr dlsym 3 ,
そして
.Fn _citrus_unload_module
は
.Xr dlclose 3
のラッパーとして実装されています。そのため
.Ft _citrus_module_t
は
.Xr dlopen 3
が返すハンドルと同一です。
.Pp
プラグインモジュールの検索パスの初期値は
.Pa \*[Lt]pats.h\*[Gt]
で
.Bd -literal -offset indent
#define _PATH_I18NMODULE	"/usr/lib/i18n"
.Ed
.Pp
と定義されていますが, 環境変数
.Ev PATH_I18NMODULE
で上書可能です。ただしセキュリティの都合上 set-user-ID あるいは set-group-ID
された実行ファイルからは無視されます。
.\" ----------------------------------------------------------------------
.Sh SEE ALSO
.Xr citrus 7
.Xr dlopen 3
.Xr dlsym 3
.Xr dlclose 3