.\"   Copyright (C) 1996-1999 Free Software Foundation, Inc.
.\"
.\"   Permission is granted to make and distribute verbatim copies of
.\" this manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\"   Permission is granted to copy and distribute modified versions of
.\" this manual under the conditions for verbatim copying, provided that
.\" the entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\"   Permission is granted to copy and distribute translations of this
.\" manual into another language, under the above conditions for modified
.\" versions, except that this permission notice may be stated in a
.\" translation approved by the Foundation.
.\"
.\" Copyright (C) 1996 Xavier Leroy.
.\"
.\" Japanese Version Copyright (C) 2002-2003 Suzuki Takashi
.\"         all rights reserved.
.\" Translated Sat Jan  4 14:23:32 JST 2003
.\"         by Suzuki Takashi.
.\"
.\"WORD:    mutex creation attribute    mutex作成時の属性
.\"WORD:    mutex attribute object  mutex属性オブジェクト
.\"WORD:    mutex kind          mutex種別
.\"WORD:    mutex kind attribute    mutex種別を表す属性
.\"WORD:    mutex type          mutex型
.\"WORD:    timed               時刻情報つき
.\"
.\"
.TH PTHREAD_MUTEXATTR 3 LinuxThreads


.SH "名前"
pthread_mutexattr_init, pthread_mutexattr_destroy, pthread_mutexattr_settype, pthread_mutexattr_gettype 
\- mutex 作成時の属性

.SH "書式"
.B #include <pthread.h>

.BI "int pthread_mutexattr_init(pthread_mutexattr_t *" attr ");"

.BI "int pthread_mutexattr_destroy(pthread_mutexattr_t *" attr ");"

.BI "int pthread_mutexattr_settype(pthread_mutexattr_t *" attr ", int " kind ");"

.BI "int pthread_mutexattr_gettype(const pthread_mutexattr_t *" attr ", int *" kind ");"

.SH "説明"

mutex の属性は mutex 作成時に、
.BR "pthread_mutex_init" (3)
の第 2 引数として mutex 属性オブジェクトを渡すことで
指定することができる。
.B "NULL"
を渡すことは、すべての属性がデフォルト値に
設定された mutex 属性オブジェクトを渡すことと同等である。

.B "pthread_mutexattr_init"
は mutex 属性オブジェクト
.I "attr"
を初期化し、すべての属性をデフォルトの値に設定する。

.B "pthread_mutexattr_destroy"
は mutex 属性オブジェクトを破壊する。
破壊された mutex 属性オブジェクトは
再び初期化されるまで再使用してはならない。
.B "pthread_mutexattr_destroy"
は LinuxThreads の実装では何もしない。

LinuxThreads はただ 1 つの mutex 属性に対応している。
それは mutex 種別 (mutex kind) で、
「速い (fast) 」 mutex を表す
.B "PTHREAD_MUTEX_FAST_NP"
か、「再帰的な (recursive) 」 mutex を表す
.B "PTHREAD_MUTEX_RECURSIVE_NP"
、「エラー検査を行なう (error checking) 」 mutex を表す
.B "PTHREAD_MUTEX_ERRORCHECK_NP"
のいずれかの値をとる。
.B "NP"
という接尾辞が示すように、
これは POSIX 標準に対するポータブルでない拡張で、
ポータブルなプログラムでは用いるべきでない。

mutex 種別は、
あるスレッドが自分自身で
.BR "pthread_mutex_lock" (3)
ですでに保持している mutex をロックしようとしたときに、
何が起こるかを決定する。
mutex が「速い (fast) 」という種別の場合、
.BR "pthread_mutex_lock" (3)
は単に呼び出しスレッドを永遠に停止させる。
mutex が「エラー検査を行なう (error checking) 」という種別の場合、
.BR "pthread_mutex_lock" (3)
はエラーコード
.B "EDEADLK"
とともに直ちに返る。
mutex が「再帰的な (recursive) 」という種別の場合、
.BR "pthread_mutex_lock" (3)
の呼び出しは成功の返り値とともに直ちに返る。
mutex を保持しているスレッドが何回ロックしたかがその mutex に記録される。
保持しているスレッドがロック解除状態に戻るためには、
同じ回数だけ
.BR "pthread_mutex_unlock" (3)
を呼び出さなければならない。

デフォルトの mutex 種別は「速い (fast) 」、
すなわち
.B "PTHREAD_MUTEX_FAST_NP"
である。

.B "pthread_mutexattr_settype"
は
.I "attr"
の mutex 種別を表す属性を
.I "kind"
で示される値に設定する。

.B "pthread_mutexattr_gettype"
は
.I "attr"
の mutex 種別を表す属性を取得し、
.I "kind"
で指し示される領域に格納する。

.SH "返り値"
.B "pthread_mutexattr_init"
および
.B "pthread_mutexattr_destroy"
、
.B "pthread_mutexattr_gettype"
は常に 0 を返す。

.B "pthread_mutexattr_settype"
は成功すると 0 を、エラーの場合非 0 のエラーコードを返す。

.SH "エラー"

エラーのとき、
.B "pthread_mutexattr_settype"
は次のようなエラーコードを返す:
.TP
.B "EINVAL"
.I "kind"
が
.B "PTHREAD_MUTEX_FAST_NP"
および
.B "PTHREAD_MUTEX_RECURSIVE_NP"
、
.B "PTHREAD_MUTEX_ERRORCHECK_NP"
のいずれでもない。

.SH "著者"
Xavier Leroy <Xavier.Leroy@inria.fr>

.SH "関連項目"
.BR "pthread_mutex_init" (3),
.BR "pthread_mutex_lock" (3),
.BR "pthread_mutex_unlock" (3).


[訳注1] glibc-linuxthreads の最新のドキュメントは Texinfo 形式で提供されている。
上の記述は glibc-linuxthreads-2.2 以降では正しくない。
以下は glibc-linuxthreads-2.3.1 の Texinfo ファイルからの引用である。
種別 (kind) が型 (type) に変更されている。

LinuxThreads はただ 1 つの mutex 属性に対応している。
それは mutex 型 (mutex type) で、
「速い (fast) 」 mutex を表す
.B "PTHREAD_MUTEX_ADAPTIVE_NP"
か、「再帰的な (recursive) 」 mutex を表す
.B "PTHREAD_MUTEX_RECURSIVE_NP"
、「時刻情報つき (timed) 」 mutex を表す
.B "PTHREAD_MUTEX_TIMED_NP"
、「エラー検査を行なう (error checking) 」 mutex を表す
.B "PTHREAD_MUTEX_ERRORCHECK_NP"
のいずれかの値をとる。
.B "NP"
という接尾辞が示すように、
これは POSIX 標準に対するポータブルでない拡張で、
ポータブルなプログラムでは用いるべきでない。

mutex 型は、
あるスレッドが自分自身で
.BR "pthread_mutex_lock" (3)
ですでに保持している mutex をロックしようとしたときに、
何が起こるかを決定する。
mutex が「速い (fast) 」という型の場合、
.BR "pthread_mutex_lock" (3)
は単に呼び出しスレッドを永遠に停止させる。
mutex が「エラー検査を行なう (error checking) 」という型の場合、
.BR "pthread_mutex_lock" (3)
はエラーコード
.B "EDEADLK"
とともに直ちに返る。
mutex が「再帰的な (recursive) 」という型の場合、
.BR "pthread_mutex_lock" (3)
の呼び出しは成功の返り値とともに直ちに返る。
mutex を保持しているスレッドが何回ロックしたかがその mutex に記録される。
保持しているスレッドがロック解除状態に戻るためには、
同じ回数だけ
.BR "pthread_mutex_unlock" (3)
を呼び出さなければならない。

デフォルトの mutex 型は「時刻情報つき (timed) 」、
すなわち
.B "PTHREAD_MUTEX_TIMED_NP"
である。


[訳注2] LinuxThreads では mutex をプロセス間で共有することはできない。
glibc-linuxthreads-2.2 以降、次の 2 つの関数が追加されている。

.BI "int pthread_mutexattr_getpshared(const pthread_mutexattr_t *" attr ", int *" pshared ");"

.I "pshared"
で指し示される領域に
.B "PTHREAD_PROCESS_PRIVATE"
を格納し、常に 0 を返す。

.BI "int pthread_mutexattr_setpshared(pthread_mutexattr_t *" attr ", int " pshared ");"

.I "pshared"
が
.B "PTHREAD_PROCESS_PRIVATE"
および
.B "PTHREAD_PROCESS_SHARED"
のいずれでもない場合、
.B "EINVAL"
を返す。
.I "pshared"
が
.B "PTHREAD_PROCESS_SHARED"
の場合、
.B "ENOSYS"
を返す。
それ以外の場合、 0 を返す。