release/man3/getspnam.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and
   2 .\" Walter Harms (walter.harms@informatik.uni-oldenburg.de)
   3 .\"
   4 .\" Distributed under GPL
   5 .\"
   6 .\" Japanese Version Copyright (c) 2004 Yuichi SATO
   7 .\"         all rights reserved.
   8 .\" Translated 2004-08-20, Yuichi SATO <ysato444@yahoo.co.jp>
   9 .\"
  10 .TH GETSPNAM 3  2010-02-25 "GNU" "Linux Programmer's Manual"
  11 .SH 名前
  12 getspnam, getspnam_r, getspent, getspent_r, setspent, endspent,fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent, lckpwdf, ulckpwdf \- shadow パスワードファイルのエントリを取得する
  13 .SH 書式
  14 .nf
  15 /* 一般的な shadow パスワードファイル API */
  16 .br
  17 .B #include <shadow.h>
  18 .sp
  19 .BI "struct spwd *getspnam(const char *" name );
  20 .sp
  21 .B struct spwd *getspent(void);
  22 .sp
  23 .B void setspent(void);
  24 .sp
  25 .B void endspent(void);
  26 .sp
  27 .BI "struct spwd *fgetspent(FILE *" fp );
  28 .sp
  29 .BI "struct spwd *sgetspent(const char *" s );
  30 .sp
  31 .BI "int putspent(struct spwd *" p ", FILE *" fp );
  32 .sp
  33 .B int lckpwdf(void);
  34 .sp
  35 .B int ulckpwdf(void);
  36 .sp
  37 /* GNU 版における拡張 */
  38 .br
  39 .B #include <shadow.h>
  40 .sp
  41 .BI "int getspent_r(struct spwd *" spbuf ,
  42 .br
  43 .BI "        char *" buf ", size_t " buflen ", struct spwd **" spbufp );
  44 .sp
  45 .BI "int getspnam_r(const char *" name ", struct spwd *" spbuf ,
  46 .br
  47 .BI "        char *" buf ", size_t " buflen ", struct spwd **" spbufp );
  48 .sp
  49 .BI "int fgetspent_r(FILE *" fp ", struct spwd *" spbuf ,
  50 .br
  51 .BI "        char *" buf ", size_t " buflen ", struct spwd **" spbufp );
  52 .sp
  53 .BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf ,
  54 .br
  55 .BI "        char *" buf ", size_t " buflen ", struct spwd **" spbufp );
  56 .fi
  57 .sp
  58 .in -4n
  59 glibc 向けの機能検査マクロの要件
  60 .RB ( feature_test_macros (7)
  61 参照):
  62 .in
  63 .sp
  64 .ad l
  65 .BR getspent_r (),
  66 .BR getspnam_r (),
  67 .BR fgetspent_r (),
  68 .BR sgetspent_r ():
  69 .RS 4
  70 _BSD_SOURCE || _SVID_SOURCE
  71 .RE
  72 .ad b
  73 .SH 説明
  74 昔は暗号化されたパスワードをパスワードファイルに
  75 見えるように公開しておいても安全だと考えられていた。
  76 Julianne Frances Haugh は shadow パスワード・スイートを実装した。
  77 これは暗号化されたパスワードを、root のみが読むことができる
  78 shadow パスワード・データベース (例えば、
  79 ローカルの shadow パスワードファイル
  80 .IR /etc/shadow ,
  81 NIS, LDAP)
  82 に保持する。
  83 .LP
  84 以下で説明する関数は、伝統的なパスワード・データベースに対する
  85 関数に似ている (例えば
  86 .BR getpwnam (3)
  87 や
  88 .BR getpwent (3)
  89 を参照)。
  90 .\" FIXME 以下を一時的にコメントアウトした。
  91 .\" PAM と nsswitch.conf の関係については、ユーザ、グループ、shadow
  92 .\" パスワードの関数についてのページから参照されるどこかにはっきりと
  93 .\" 記載しておく必要がある。
  94 .\" (Jul 2005, mtk)
  95 .\"
  96 .\" この shadow パスワードの設定は
  97 .\" PAM (pluggable authentication modules) で取り替えることができる。
  98 .\" 現在のところ、どの情報源を使用するかは
  99 .\" .I /etc/nsswitch.conf
 100 .\" ファイルに記述される。
 101 .LP
 102 .BR getspnam ()
 103 関数は、ユーザ名
 104 .I name
 105 にマッチする shadow パスワード・データベースのエントリを
 106 要素毎に分解し、各要素を格納した構造体へのポインタを返す。
 107 .LP
 108 .BR getspent ()
 109 関数は shadow パスワード・データベースにおける次のエントリへのポインタを返す。
 110 入力ストリームにおける位置は、
 111 .BR setspent ()
 112 で初期化される。
 113 読み込みが終わった後に、
 114 .BR endspent ()
 115 を呼び出すと、リソースを解放できる。
 116 .\" 最初に getspent() を呼び出す前に、
 117 .\" setspent() を呼び出さなければならないシステムもある。
 118 .\" glibc ではその必要がない。
 119 .LP
 120 .BR fgetspent ()
 121 関数は
 122 .BR getspent ()
 123 に似ているが、
 124 .BR setspent ()
 125 で暗黙のうちにオープンされるストリームではなく、与えられたストリームを使う。
 126 .LP
 127 .BR sgetspent ()
 128 関数は与えられた文字列
 129 .I s
 130 を解析し struct
 131 .I spwd
 132 に格納する。
 133 .LP
 134 .BR putspent ()
 135 関数は与えられた struct
 136 .I spwd
 137 .I *p
 138 の内容を shadow パスワードファイル形式のテキスト行でストリーム
 139 .I fp
 140 に書き出す。
 141 空文字列として、
 142 値が NULL の文字列エントリと値が \-1 の数値エントリが
 143 書き出される。
 144 .LP
 145 .BR lckpwdf ()
 146 関数は、 shadow パスワード・データベースを
 147 多重同時アクセスから守るためのものである。
 148 この関数はロックの獲得を試み、
 149 成功した場合は 0 を返す。
 150 失敗した場合 (15 秒以内にロックが取得できなかった場合) は \-1 を返す。
 151 .BR ulckpwdf ()
 152 関数はロックを再び解放する。
 153 shadow パスワードファイルへの直接アクセスから
 154 保護する手段がない点に注意すること。
 155 .BR lckpwdf ()
 156 を使うプログラムだけがロックを通知できる。
 157 .LP
 158 これらの関数はオリジナルの shadow API を構成していた関数であり、
 159 いろいろなシステムで広く利用可能である。
 160 .\" libc5 でも利用可能である。
 161 .\" SUN には sgetspent() がない。
 162 .SS リエントラント版
 163 パスワード・データベースに対するリエントラント版と同じように、
 164 glibc には shadow パスワードファイルに対してリエントラント版がある。
 165 .BR getspnam_r ()
 166 関数は
 167 .BR getspnam ()
 168 と似ているが、取得した shadow パスワード構造体を
 169 .I spbuf
 170 が指す領域に格納する。
 171 shadow パスワード構造体は文字列群へのポインタを含み、
 172 これらの文字列群はサイズ
 173 .I buflen
 174 のバッファ
 175 .I buf
 176 に格納される。
 177 .I *spbufp
 178 には (成功した場合は) 結果へのポインタが格納され、
 179 (エントリが見つからなかった場合またはエラーが起こった場合は)
 180 NULL が格納される。
 181 .LP
 182 関数
 183 .BR getspent_r (),
 184 .BR fgetspent_r (),
 185 .BR sgetspent_r ()
 186 はそれぞれリエントラントでないバージョンと同様の機能を持つ。
 187 .LP
 188 glibc でないシステムにもこれらと同じ名前の関数があるが、
 189 プロトタイプが異なることも多い。
 190 .\" SUN には sgetspent_r() がない。
 191 .SS 構造体
 192 shadow パスワード構造体は \fI<shadow.h>\fP で以下のように定義されている:
 193 .sp
 194 .in +4n
 195 .nf
 196 struct spwd {
 197     char *sp_namp;     /* ログイン名 */
 198     char *sp_pwdp;     /* 暗号化されたパスワード */
 199     long  sp_lstchg;   /* 最終更新日
 200                           (1970-01-01 00:00:00 +0000 (UTC)) からの日数) */
 201     long  sp_min;      /* 変更が出来るようになるまでの最短日数 */
 202     long  sp_max;      /* 変更をしなくてもよい最長日数 */
 203     long  sp_warn;     /* パスワードが期限切れになる前に
 204                           ユーザに変更の警告を出す日数 */
 205     long  sp_inact;    /* パスワードが期限切れになってから
 206                           アカウントが無効になるまでの日数 */
 207     long  sp_expire;   /* アカウントが無効になる日付
 208                           (1970-01-01 00:00:00 +0000 (UTC)) からの日数) */
 209     unsigned long sp_flag;  /* 予約フィールド */
 210 };
 211 .fi
 212 .in
 213 .SH 返り値
 214 ポインタを返す関数は、これ以上エントリがない場合や
 215 処理中にエラーが発生した場合 NULL を返す。
 216 \fIint\fP を返り値として持つ関数は、
 217 成功した場合 0 を返し、失敗した場合 \-1 を返す。
 218 .LP
 219 リエントラント版でない関数では、返り値が静的な領域を指しており、
 220 引き続いてこれらの関数を呼び出した場合に上書きされる可能性がある。
 221 .LP
 222 リエントラント版の関数は、成功した場合に 0 を返す。
 223 エラーの場合は、エラー番号が返される。
 224 .SH エラー
 225 .TP
 226 .B ERANGE
 227 与えられたバッファが小さすぎる。
 228 .SH ファイル
 229 .TP
 230 .I /etc/shadow
 231 ローカルの shadow パスワード・データベースファイル
 232 .TP
 233 .I /etc/.pwd.lock
 234 ロックファイル
 235 .LP
 236 インクルードファイル
 237 .I <paths.h>
 238 は定数
 239 .B _PATH_SHADOW
 240 を定義している。
 241 これは shadow パスワードファイルのパス名である。
 242 .SH 準拠
 243 shadow パスワード・データベースと関連 API は POSIX.1-2001
 244 には記載されていない。しかしながら、多くの他のシステムでも
 245 同様の API が提供されている。
 246 .SH 関連項目
 247 .BR getgrnam (3),
 248 .BR getpwnam (3),
 249 .BR getpwnam_r (3),
 250 .BR shadow (5)