getspnam

Section: C Library Functions (3)
Updated: 2026-02-08
Index JM Home Page roff page
 

名前

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

ライブラリ

標準 C ライブラリ (libc,~-lc)  

書式

/* 一般的な 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 *stream);
struct spwd *sgetspent(const char *s);

int putspent(const struct spwd *p, FILE *stream);

int lckpwdf(void);
int ulckpwdf(void);

/* GNU による拡張 */
#include <shadow.h>

int getspent_r(size_t size;
               struct spwd *spbuf,
               char buf[size], size_t size,
               struct spwd **spbufp);
int getspnam_r(size_t size;
               const char *name, struct spwd *spbuf,
               char buf[size], size_t size,
               struct spwd **spbufp);

int fgetspent_r(size_t size;
               FILE *stream, struct spwd *spbuf,
               char buf[size], size_t size,
               struct spwd **spbufp);
int sgetspent_r(size_t size;
               const char *s, struct spwd *spbuf,
               char buf[size], size_t size,
               struct spwd **spbufp);

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

getspent_r(), getspnam_r(), fgetspent_r(), sgetspent_r():

    glibc 2.19 以降:
        _DEFAULT_SOURCE
    glibc 2.19 以前:
        _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 パスワードファイル形式のテキスト行で stream に書き出す。 空文字列として、 値が NULL の文字列エントリーと値が -1 の数値エントリーが 書き出される。

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

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

リエントラント版

Analogous to the reentrant functions for the password database, glibc also has reentrant functions for the shadow password database. The getspnam_r() function is like getspnam() but stores the retrieved shadow password structure in the space pointed to by spbuf. This shadow password structure contains pointers to strings, and these strings are stored in the buffer buf of size size. A pointer to the result (in case of success) or NULL (in case no entry was found or an error occurred) is stored in *spbufp.

関数 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;  /* 予約フィールド */
};
 

返り値

The functions that return a pointer return NULL if no more entries are available or if an error occurs during processing. The functions which have int as the return value return 0 for success and -1 for failure, with errno set to indicate the error.

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

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

エラー

EACCES
呼び出し元が shadow パスワードファイルにアクセスする許可を持っていない。
ERANGE
与えられたバッファーが小さすぎる。
 

ファイル

/etc/shadow
ローカルの shadow パスワードデータベースファイル
/etc/.pwd.lock
ロックファイル

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

属性

この節で使用されている用語の説明については、 attributes(7) を参照。
インターフェース属性値
getspnam() Thread safety MT-Unsafe race:getspnam locale
getspent() Thread safety MT-Unsafe race:getspent race:spentbuf locale
setspent(), endspent(), getspent_r() Thread safety MT-Unsafe race:getspent locale
fgetspent() Thread safety MT-Unsafe race:fgetspent
sgetspent() Thread safety MT-Unsafe race:sgetspent
putspent(), getspnam_r(), sgetspent_r() Thread safety MT-Safe locale
lckpwdf(), ulckpwdf(), fgetspent_r() Thread safety MT-Safe

In the above table, getspent in race:getspent signifies that if any of the functions setspent(), getspent(), getspent_r(), or endspent() are used in parallel in different threads of a program, then data races could occur.  

バージョン

Many other systems provide a similar API.  

標準規格

なし。  

関連項目

getgrnam(3), getpwnam(3), getpwnam_r(3), shadow(5)


 

Index

名前
ライブラリ
書式
説明
リエントラント版
構造体
返り値
エラー
ファイル
属性
バージョン
標準規格
関連項目

This document was created by man2html, using the manual pages.