GETSPNAM(3)

名前
getspnam, getspnam_r, getspent, getspent_r, setspent, endspent,fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent, lckpwdf, ulckpwdf - shadow パスワードファイルのエントリを取得する

書式
/* 一般的な shadow パスワードファイル API */
#include <shadow.h>

struct spwd *getspnam(const char *name);

struct spwd *getspent(void);

void setspent(void);

void endspent(void);

struct spwd *fgetspent(FILE *fp);

struct spwd *sgetspent(const char *s);

int putspent(struct spwd *p, FILE *fp);

int lckpwdf(void);

int ulckpwdf(void);

/* GNU 版における拡張 */
#include <shadow.h>

int getspent_r(struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

int getspnam_r(const char *name, struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

int fgetspent_r(FILE *fp, struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

int sgetspent_r(const char *s, struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

glibc 向けの機能検査マクロの要件 (feature_test_macros(7) 参照):

getspent_r(), getspnam_r(), fgetspent_r(), sgetspent_r():
    _BSD_SOURCE || _SVID_SOURCE

説明
昔は暗号化されたパスワードをパスワードファイルに 見えるように公開しておいても安全だと考えられていた。 Julianne Frances Haugh は shadow パスワード・スイートを実装した。 これは暗号化されたパスワードを、root のみが読むことができる shadow パスワード・データベース (例えば、 ローカルの shadow パスワードファイル /etc/shadow, NIS, LDAP) に保持する。

以下で説明する関数は、伝統的なパスワード・データベースに対する 関数に似ている (例えば getpwnam(3) や getpwent(3) を参照)。

getspnam() 関数は、ユーザ名 name にマッチする shadow パスワード・データベースのエントリを 要素毎に分解し、各要素を格納した構造体へのポインタを返す。

getspent() 関数は shadow パスワード・データベースにおける次のエントリへのポインタを返す。 入力ストリームにおける位置は、 setspent() で初期化される。 読み込みが終わった後に、 endspent() を呼び出すと、リソースを解放できる。

fgetspent() 関数は getspent() に似ているが、 setspent() で暗黙のうちにオープンされるストリームではなく、与えられたストリームを使う。

sgetspent() 関数は与えられた文字列 s を解析し struct spwd に格納する。

putspent() 関数は与えられた struct spwd *p の内容を shadow パスワードファイル形式のテキスト行でストリーム fp に書き出す。 空文字列として、 値が NULL の文字列エントリと値が -1 の数値エントリが 書き出される。

lckpwdf() 関数は、 shadow パスワード・データベースを 多重同時アクセスから守るためのものである。 この関数はロックの獲得を試み、 成功した場合は 0 を返す。 失敗した場合 (15 秒以内にロックが取得できなかった場合) は -1 を返す。 ulckpwdf() 関数はロックを再び解放する。 shadow パスワードファイルへの直接アクセスから 保護する手段がない点に注意すること。 lckpwdf() を使うプログラムだけがロックを通知できる。

これらの関数はオリジナルの shadow API を構成していた関数であり、 いろいろなシステムで広く利用可能である。

  リエントラント版
パスワード・データベースに対するリエントラント版と同じように、 glibc には shadow パスワードファイルに対してリエントラント版がある。 getspnam_r() 関数は getspnam() と似ているが、取得した shadow パスワード構造体を spbuf が指す領域に格納する。 shadow パスワード構造体は文字列群へのポインタを含み、 これらの文字列群はサイズ buflen のバッファ buf に格納される。 *spbufp には (成功した場合は) 結果へのポインタが格納され、 (エントリが見つからなかった場合またはエラーが起こった場合は) NULL が格納される。

関数 getspent_r(), fgetspent_r(), sgetspent_r() はそれぞれリエントラントでないバージョンと同様の機能を持つ。

glibc でないシステムにもこれらと同じ名前の関数があるが、 プロトタイプが異なることも多い。

  構造体
shadow パスワード構造体は <shadow.h> で以下のように定義されている:

struct spwd {
    char *sp_namp;     /* ログイン名 */
    char *sp_pwdp;     /* 暗号化されたパスワード */
    long  sp_lstchg;   /* 最終更新日
                          (1970-01-01 00:00:00 +0000 (UTC)
                           からの日数) */
    long  sp_min;      /* 変更が出来るようになるまでの最短日数 */
    long  sp_max;      /* 変更をしなくてもよい最長日数 */
    long  sp_warn;     /* パスワードが期限切れになる前に
                          ユーザに変更の警告を出す日数 */
    long  sp_inact;    /* パスワードが期限切れになってから
                          アカウントが無効になるまでの日数 */
    long  sp_expire;   /* アカウントが無効になる日付
                          (1970-01-01 00:00:00 +0000 (UTC)
                           からの日数) */
    unsigned long sp_flag;  /* 予約フィールド */
};

返り値
ポインタを返す関数は、これ以上エントリがない場合や 処理中にエラーが発生した場合 NULL を返す。 int を返り値として持つ関数は、 成功した場合 0 を返し、失敗した場合、 -1 を返し、 errno にエラーの原因を示す値を設定する。

リエントラント版でない関数では、返り値が静的な領域を指しており、 引き続いてこれらの関数を呼び出した場合に上書きされる可能性がある。

リエントラント版の関数は、成功した場合に 0 を返す。 エラーの場合は、エラー番号が返される。

エラー

EACCES
    呼び出し元が shadow パスワードファイルにアクセスする許可を持っていない。

ERANGE
    与えられたバッファが小さすぎる。

ファイル

/etc/shadow
    ローカルの shadow パスワード・データベースファイル

/etc/.pwd.lock
    ロックファイル

インクルードファイル <paths.h> は定数 _PATH_SHADOW を定義している。 これは shadow パスワードファイルのパス名である。

準拠
shadow パスワード・データベースと関連 API は POSIX.1-2001 には記載されていない。しかしながら、多くの他のシステムでも 同様の API が提供されている。

関連項目
getgrnam(3), getpwnam(3), getpwnam_r(3), shadow(5)

この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.54 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。