path: root/ja_JP.eucJP/man/man3/login_cap.3

.\" Copyright (c) 1995 David Nugent <davidn@blaze.net.au>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, is 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.
.\" 3. This work was done expressly for inclusion into FreeBSD.  Other use
.\"    is permitted provided this notation is included.
.\" 4. Absolutely no warranty of function or purpose is made by the author
.\"    David Nugent.
.\" 5. Modifications may be freely made to this file providing the above
.\"    conditions are met.
.\"
.\" %Id: login_cap.3,v 1.9 1998/06/06 05:50:42 jkoshy Exp %
.\"
.\" $FreeBSD$
.Dd December 27, 1996
.Os FreeBSD
.Dt LOGIN_CAP 3
.Sh 名称
.Nm login_getclassbyname ,
.Nm login_close ,
.Nm login_getclass ,
.Nm login_getpwclass ,
.Nm login_getuserclass ,
.Nm login_getcapstr ,
.Nm login_getcaplist ,
.Nm login_getcaptime ,
.Nm login_getcapnum ,
.Nm login_getcapsize ,
.Nm login_getcapbool ,
.Nm login_getstyl
.Nd ログインクラスデータベース
に対するプログラミングインタフェース
.Sh 書式
.Fd #include <sys/types.h>
.Fd #include <login_cap.h>
.Ft void
.Fn login_close "login_cap_t * lc"
.Ft login_cap_t *
.Fn login_getclassbyname "const char *nam" "const struct passwd *pwd"
.Ft login_cap_t *
.Fn login_getclass "const char *nam"
.Ft login_cap_t *
.Fn login_getpwclass "const struct passwd *pwd"
.Ft login_cap_t *
.Fn login_getuserclass "const struct passwd *pwd"
.Ft char *
.Fn login_getcapstr "login_cap_t *lc" "const char *cap" "char *def" "char *error"
.Ft char **
.Fn login_getcaplist "login_cap_t *lc" "const char *cap" "const char *chars"
.Ft char *
.Fn login_getpath "login_cap_t *lc" "const char *cap" "char *error"
.Ft rlim_t
.Fn login_getcaptime "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
.Ft rlim_t
.Fn login_getcapnum "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
.Ft rlim_t
.Fn login_getcapsize "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
.Ft int
.Fn login_getcapbool "login_cap_t *lc" "const char *cap" "int def"
.Ft char *
.Fn login_getstyle "login_cap_t *lc" "char *style" "const char *auth"
.Pp
.Sh 解説
これらの関数は
.Xr login.conf 5
に備わっているログインクラスデータベース
に対するプログラミングインタフェースを表します。このデータベースに
収録されているのは、CAPABILITIES、属性およびデフォルト環境、
ユーザや特殊ユーザとしての稼動中のプログラムに対する課金上の設定などで、
.Pa /etc/master.passwd
の登録データ内のログインクラスフィールドに定義されています。
.Pp
.Xr login.conf 5
内のレコードは、コロン
.Ql \&:
で分離されるフィールドで
構成されています。各レコードの最初のフィールドはデータベース全体で一意な
レコードのための複数の識別子です。それぞれ '|' で分離されており、
最後尾に 'name' 識別子が付いていることもあります。
レコードの残りのフィールドは keyword/data のペアで構成されます。
ロングラインは空のレコード内でバックスラッシュが後ろにつき、
次の連続する行は随時読み取られるようになっています。
このことは、キーワードが 2 つの意味にある文字に限定されないことを除けば
.Xr termcap 5
で使用されている形式と類似しており、読み易すく改善されている点が利点です。
termcap レコードの場合と同様に、tc=<recordid>
が記述されているフィールドによって複数レコードを相互に
関連させることができます (レコードが包含関係にあります)。
.Aq Pa recordid
で示されるすべてのレコードは発生した箇所で tc= フィールドにより
置きかえられます。
CAPABILITIES データベースの形式と利用方法に関する詳細については、
.Xr getcap 3
を参照してください。
.Pp
.Nm login_cap
インタフェースには、tc= 参照の拡張により、
ログインレコードクラスを取り出す便利な方法が備わっています。
プログラム要求により、
.Fn login_getclass ,
.Fn login_getpwclass ,
.Fn login_getuserclass
または
.Fn login_getclassbyname
のうちどれか 1 つを呼び
出して実行します。それぞれの関数はログイン CAPABILITIES 構造体
.Ft login_cap_t
を戻り値として返し、
API
の残りを使用して指定した値をデータベースに引き続き
問い合せするときに使用されます。
login_cap_t
が不要になった場合は、関数
.Fn login_close
の呼び出しを実行して使用していたリソースをすべて解放する
必要があります。
.Pp
login_cap_t の構造は login_cap.h で次のように定義されます。
.Bd -literal -offset indent
typedef struct {
	char *lc_class;
	char *lc_cap;
	char *lc_style;
} login_cap_t;
.Ed
.Pp
.Ar lc_class
メンバーには取り出したログインクラスの名前に対するポインタ
があります。これは、
.Fn login_getclass
または
.Fn login_getuserclass
を使用したクラス名により
.Fn login_getclassbyname
経由で直接的に、または、
.Fn login_getpwclass
を使用したユーザのログインレコード経由で間接的に
要求されたものと必ずしも同じではありません。参照されたユーザに
 /etc/master.passwd
で定義されたログインクラスがない場合、クラス名は NULL
か空ストリングです。
また、定義されたクラスがデータベースに存在しない場合、
各関数は、'default' という ID のレコードを探索し、
.Ar lc_class
フィールドにその名前を戻り値として取得します。
.Pp
.Ar lc_cap
フィールドは、ライブラリで内部的に使用され、
拡張されたログイン CAPABILITIES レコードを保持します。
プログラムからの例外要求では、低次の
.Fn getcap
方式の関数とともにレコードを直接アクセスしようとしてこれを
使用する傾向があります。
.Pp
.Ar lc_style
フィールドに対しては、ログイン自身の操作プログラムからの
要求に従って、関数
.Fn login_getstyle
により、認可方式が設定されます。
.Pp
前述したように、関数
.Fn get*class
は、CAPABILITIES データベースのマッチング
またはデフォルトレコードのアクセスに使用される login_cap_t オブジェクトを
戻り値として返します。
.Fn getclassbyname
は 2 つの引数を受け取ります。
最初のものは取り出し対象レコードのレコード識別子で、
2 番めのものは、任意指定のディレクトリ名です。最初の引数
.Ar name
が NULL か、空ストリング、
あるいは補助的なまたはシステムのログインクラスデータベースに
クラスが存在しない場合、システム
.Em デフォルト
レコードが代わりに返されてきます。
2 番めの引数
.Ar dir
パラメータが NULL のとき、
システムログインクラスデータベースだけが使用されますが、
NULL でないときは、
.Xr .login_conf 5
というファイル内で名前付きディレクトリが検索され、中にある
CAPABILITIES レコードがシステムデフォルトを上書きします。
この体系によりユーザは、'me' という IDのレコードがある
プライベートクラスに対するクラスレコードを生成して、
システムログインクラス・データベースのレコード
におけるログイン設定値を上書きできます。
Login のコンテキストでは、次の 2 つの理由により、
ユーザが上書きできないオプションがあります。
第 1 に、リソース設定値やデフォルトのプロセス優先順位などの
多くのオプションでは、効果を発揮させるためにルート権限が必要であること、
第 2 に、ユーザファイルの他のフィールドは、
ログインの初期段階ではセキュリティや管理上の理由から、
十分な検討が行われていません。どの設定がユーザが
上書きできるのかについての詳細については、
.Xr login.conf 5
を参照してください。実際には、これらは、そうでない場合に常に
初期起動シエルスクリプトで上書きされるユーザのデフォルトログイン環境に
よって明確に制限されます。ユーザの
.Pa .login_conf
は、ログイン時、シエルが呼ばれる前に
実行される優先ログイン環境設定での簡便な方法をユーザに提供します。
.Pp
指定レコードが NULL か、空または存在しないとき、さらに不測の事態に
備えてデフォルトレコードがシステムにない場合、メモリアロケーションエラー
になるか、あるいは
.Xr cgetent 3
が何らかの理由によりログイン CAPABILITIES データベースに
アクセスできなくなり、NULL を返してきます。
.Pp
関数
.Fn login_getpwclass ,
.Fn login_getclass
および
.Fn login_getuserclass
で、ユーザパスワード登録情報に対応するログインクラスレコードの取り出し、
.Fn login_getclassbyname
呼び出しによるクラス名の取り出しができます。
処理が失敗した場合は NULL が返されます。これらの関数の間で、
.Fn login_getuserclass
はユーザによる上書きが可能なユーザホームディレクトリ上の .login_conf
を含んでいますが、
.Fn login_getpwclass
および
.Fn login_getclass
では、それへの参照を
.Pa /etc/login.conf
上のシステムログインクラスに制限している点で異なります。
.Fn login_getpwclass
が
.Fn login_getclass
と異なる唯一の点は、パスワードデータベースでの定義がないときに
ユーザルートをシステムルートとして認めていることです。
他方、パスワードのポインタが NULL のとき、
またはユーザレコードにログインクラスがない場合、
システムの「デフォルト」登録レコードの取得が行われます。
.Pp
プログラムで login_cap_t オブジェクトを使用する必要がなくなると、
.Fn login_close
呼び出しを実行し、ログインクラスで使用していたリソースを解放します。
.Fn login_close
は NULL ポインタを返しますが、これには弊害はありません。
.Pp
残りの関数は、個別の権限レコードの取り出しに使用されます。各関数は、
login_cap_t オブジェクトを第 1 引数とし、
CAPABILITIES タグを第 2 引数とします。残りのパラメータは、
CAPABILITIES レコードが見つからないときの
デフォルトまたはエラー値を指定します。
受け渡されるパラメータの型は関連する CAPABILITIES のタイプによって
変わってきます。
たとえば、ストリング、リスト、時間値、ファイルやメモリサイズ、
パス (コロンで分離されたデイレクトリリストから構成される)、
またはバイナリ値フラグなどです。
.Pp
このグループのすべての関数では、ポインタを返すとき
.Xr free 3
呼出を使用できないことに注意してください。
検索や CAPABILITIES タグ処理の間に割り当てられたメモリは、
後続するこのグループの関数呼び出しで自動的に再利用されるか、
または
.Fn login_close
呼び出しで解除されます。
.Bl -tag -width "login_gatcaplist()"
.Fn login_getcapstr
この関数は、単純ストリング CAPABILITIES を返します。
ストリングが見つからないとき、
.Ar def
内の定義値がデフォルト値として返されます。エラーが発生したとき、
.Ar error
パラメータの値が返されます。
.Pp
.It Fn login_getcaplist
この関数は、名前付き CAPABILITY タグの値を NULL で
終了する配列の値リストとして返します。ログインクラスデータベースには、
リストタイプのタグがあり、複数のカンマまたはスペースで分離した値で
構成されています。通常、この関数は直接アプリケーションから
呼び出されることはなく、
.Fn login_getstyle
経由で間接的に使用されます。
.Pp
.It Fn login_getpath
この関数は、コロン
.Ql \&:
で分離されたディレクトリリストを返します。
この関数の呼出しが実行される CAPABILITY タグはスペースで分離された
デイレクトリリストで構成されます。
.Pp
.It Fn login_getcaptime
 この関数は、時、分、秒 (デフォルト)、年 (365 日基準)、週、
あるいはこれらの任意の組み合わせで表される値の特殊な
CAPABILITY タグに関連する時間値を返します。
接尾語により使用される単位を決定します。
S は秒を、M は分を、H は時を、D は日を、W は週を表し、
Y は 365 日基準による年を表します。
単位接尾語では大文字、小文字の区別はありません。
.Pp
時間値は、通常はリソースの設定値、課金システム、およびセッション制限値に
使用されます。オペレーティングシステムやコンパイラ (FreeBSD 対応) で
サポートしている場合、戻り値は 2 次元 (long long) の
.Em rlim_t
型になります。値 "inf" または "infinity" で無限の値を表せます。
その場合 RLIM_INFINITY が戻り値となります。
.Pp
.It Fn login_getcapnum
この関数は、タグに関する数値を返します。数値は、
tag=<value> または標準的な
.Fn cgetnum
書式 tag#<value> で表現されます。
最初の書式は 2 番目のものより優先的に使用されます。
2 番めの書式は、
.Xr getcap 3
データベースの書式との互換性と整合性があり、数値タイプの場合、
数値のデリミタとして
.Ql \&#
が使われます。最初の書式の場合、指定される値は "inf"
または "infinity" で、戻り値は RLIM_INFINITY になります。
指定された CAPABILITY タグを見つけることができない場合、
.Ar def
パラメータが返されます。
エラーが起きると、
.Ar error
パラメータが返されます。
.Pp
.It Fn login_getcapsize
.Fn login_getcapsize
は、サイズ（ファイルまたはメモリの場合）を表す値を、
バイト数（デフォルト）、512 バイトのブロック数、
KB,MB,GB
表示で返します。また
.Ar long long
タイプをサポートしているシステムであれば、
TB 表示もあります。使用されている接尾語により単位、複合値を
決定し、単位は組み合せた形で使用されます。(例えば、
1m500k = 1.5megabytes) 接尾語がない値 A はバイトを、
B は 512 バイトブロックを、
K は kilobyte を、
M は megabyte を、
G は gigabyte を、
そして T は terrabyte を表します。
大文字と小文字の区別はありません。エラー値が返ってくるのは、
ログイン CAPABILITIES データベースエラーがあるか、
間違った接尾語が使用されているか、または数値が変換ができない場合です。
.Pp
.It Fn login_getcapbool
この関数は、特定のフラグに関連したバイナリ値を返します。
指定された CAPABILITY タグがないか、
"tag@" (boolean フラグの詳細については
.Xr getcap 3
を参照) により無効にされているとき、0 が返ってきます。
タグが見つかれば 1 が返ります。
.Pp
.It Fn login_getstyle
この関数は、ログイン認可システムで使用され、特定の
ケースで有効なログインの形式を決定します。
関数は、3 つのパラメータと、
.Nm login_cap
登録レコードそのもの、および 2 つの任意指定パラメータ、'auth'
と 'style' の認可タイプを受け取り、
これらを用いてこれらのルールと矛盾しない認可スタイルを決定します。
.Pp
.Bl -bullet -indent offset
.It
.Ql auth
が NULL または 空ストリングでなければ、CAPABILITY レコードの
"auth-<auth>" タイプのタグの検索を行います。
存在しなければ、デフォルトのデフォルトタグ "auth=" を検索します。
.It
先のステップで正当な認可リストが見つからない場合、"passwd"
がデフォルトの認可リストとされます。
.It
.Ql style
が NULL でも空でもないとき、先行ステップで見つかった認可方式の
リストからそれを検索します。
.It
.Ql style
が NULLか空ストリングのとき、"passwd"をデフォルトの認可に使用します。
.It
.Ql style
が、認可方式の選択リストに見つかった場合、それを返し、
そうでないときは NULL を返します。
.El
.Pp
この体系により、管理者は、アクセス方式に従って、システムが受け取る
認可方式を決定します。たとえば、管理者がネットワークを経由したシステムへの
アクセスに使用された認証方式として、skey または kerberos を要求します。
また、直接のダイアルアップまたはコンソールログイン経由での標準的方式を
要求することもあり、"snooping" ネットワークパケットによりパスワードが
発見されるリスクを著しく減少させられます。
.El
.Sh 関連項目
.Xr getcap 3 ,
.Xr login_class 3 ,
.Xr login.conf 5 ,
.Xr termcap 5