<!doctype linuxdoctr SYSTEM  [

<!--
<!entity % latex "INCLUDE">
<!entity % html  "IGNORE">
<![ %latex; [ <!entity newpage PI "\newpage"> ]]>
<![ %html; [ <!entity newpage PI "<HR>"> ]]>
<!entity newpage PI "">
-->
]>

<article>



<title> The Venus kernel interface
<author> Peter J. Braam
<date>v1.2, Mar 18, 1998
<trans> 野本 浩一 (<tt>hng@ps.ksky.or.jp</tt>)
<tdate> v1.2j, November 26, 2001 

<!--
<abstract> This document describes the communication between Venus and
kernel level file system code needed for the operation of the Coda
filesystem.  This version document is meant to describe the current interface (version 1.0) as well as improvements we envisage.
</abstract>
-->
<!--draft2-->
<abstract> この文書は Coda ファイルシステムの操作に必要な Venus とカーネ
ルレベルファイルシステムのコードとの間のコミュニケーションについて記述し
ます。この文書改訂で現行のインターフェース (バージョン 1.0) と、私たちが
考えている改善についても記述しています。
</abstract>

<toc>
<!--
&newpage;<sect> Introduction <P> 
-->
<sect> はじめに <P> 

<!--
A key component in the Coda Distributed File System is the cache
manager, <em>Venus</em>.  
-->
<!--draft2-->
Coda 分散ファイルシステムの鍵となる構成要素はキャッシュマネージャ
<em>Venus</em> です。

<!--TYPO appropiate は appropriate-->
<!--
When processes on a Coda enabled system access files in the Coda
filesystem, requests are directed at the filesystem layer in the
operating system. The operating system will communicate with Venus to
service the request for the process.  Venus manages a persistent
client cache and makes remote procedure calls to Coda file servers and
related servers (such as authentication servers) to service these
requests it receives from the operating system.  When Venus has
serviced a request it replies to the operating system with appropiate
return codes, and other data related to the request.  Optionally the
kernel support for Coda may maintain a minicache of recently processed
requests to limit the number of interactions with Venus.  Venus
possesses the facility to inform the kernel when elements from its
minicache are no longer valid.
-->
<!--draft2-->
システムで Coda が有効な場合、プロセスが Coda ファイルシステム内のファイ
ルにアクセスする際に、要求はオペレーティングシステム内のファイルシステム
層に転送されます。プロセスの要求をサービスするために、オペレーティングシ
ステムは Venus と通信するでしょう。Venus はオペレーティングシステムから
の要求を受信し、これをサービスするために永続的なクライアントキャッシュを
管理し、Coda ファイルサーバおよび (認証サーバのような) 関連するサーバへ
リモートプロシージャコールを行います。Venus が要求のサービスを完了した場
合、適切なリターンコードおよび要求に関連するデータをオペレーティングシス
テムへ応答します。実装は任意ですが、Coda のカーネルサポートは Venus との
会話を減らすために、最近処理した要求のミニキャッシュを保持するようにも出
来ます。Venus はそのミニキャッシュの要素が無効になった際に、そのことをカー
ネルに通知する機構を持っています。

<!--
This document describes precisely this communication between the
kernel and Venus.  The definitions of so called upcalls and downcalls
will be given with the format of the data they handle. We shall also
describe the semantic invariants resulting from the calls.
-->
<!--draft2-->
この文書はカーネルと Venus 間のコミュニケーションの細部について記述しま
す。upcall および downcall と呼ばれる機構の定義を、それらが扱うデータの
フォーマットとともに説明します。コールの結果の意味の不変部も記述します。

<!--
Historically Coda was implemented in a BSD file system in Mach 2.6.
The interface between the kernel and Venus is very similar to the BSD
VFS interface.  Similar functionality is provided, and the format of
the parameters and returned data is very similar to the BSD VFS.  This
leads to an almost natural environment for implementing a kernel level
filesystem driver for Coda in a BSD system.  However, other operating
systems such as Linux and Windows 95 and NT have virtual filesystem
with different interfaces.
-->
歴史的に Coda は Mach 2.6 の BSD ファイルシステムで実装されました。カー
ネルと Venus 間のインターフェースは BSD VFS インターフェースにとても似て
います。同様の機能性を提供し、引き数および返されるデータのフォーマットも
BSD VFS にとても似ています。これは BSD システムで Coda 用カーネルレベル
ファイルシステムドライバを実装するためのとても自然な環境をもたらします。
しかしながら、Linux や Windows95, NT のような他のオペレーティングシステ
ムは、異なるインターフェースを備えたバーチャルファイルシステムを持ってい
ます。

<!--
To implement Coda on these systems some reverse engineering of the
Venus/Kernel protocol is necessary.  Also it came to light that other
systems could profit significantly from certain small optimizations
and modifications to the protocol. To facilitate this work as well as
to make future ports easier, communication between Venus and the
kernel should be documented in great detail.  This is the aim of this
document.
-->
<!--draft2-->
これらのシステム上で Coda を実装するには、Venus/カーネルプロトコルのリバー
スエンジニアリングが必要です。さらに、プロトコルに対するいくつかの小さな
最適化や修正により、他のシステムでは著しく性能の向上が図れることが明らか
になっています。この作業を促進し将来の移植を容易にするために、Venus とカー
ネル間のコミュニケーションはもっと詳しい文書が必要なはずです。 これがこ
の文書の目標です。

<!--TYPO CreateFile, は CreateFile-->
<!--
&newpage;<sect> Servicing Coda filesystem calls <p> The service of a
request for a Coda file system service originates in a process <bf/P/
which accessing a Coda file. It makes a system call which traps to the
OS kernel. Examples of such calls trapping to the kernel are <em>read,
write, open, close, create, mkdir, rmdir, chmod</em> in a Unix
context.  Similar calls exist in the Win32 environment, and are named
<em>CreateFile, </em>.
-->
<!--draft2-->
<sect> Coda ファイルシステムサービス用のコール <p> Coda ファイ
ルシステムサービス要求のサービスは、Coda ファイルにアクセスするプロセス
<bf/P/ で起こります。それは OS のカーネルへトラップするシステムコールを
行います。Unix コンテキストにおけるカーネルにトラップするようなコールの
例は <em>read, write, open, close, create, mkdir, rmdir, chmod</em> など
です。Win32 環境にも同様のコールは存在し、<em>CreateFile</em> と名付けら
れています。

<!--
Generally the operating system handles the request in a virtual
filesystem (VFS) layer, which is named I/O Manager in NT and IFS
manager in Windows 95.  The VFS is responsible for partial processing
of the request and for locating the specific filesystem(s) which will
service parts of the request.  Usually the information in the path
assists in locating the correct FS drivers.  Sometimes after extensive
pre-processing, the VFS starts invoking exported routines in the FS
driver.  This is the point where the FS specific processing of the
request starts, and here the Coda specific kernel code comes into
play.
-->
<!--draft2-->
一般にオペレーティングシステムは要求をバーチャルファイルシステム (VFS)
層で扱います。この層は NT では I/O マネージャ、Windows 95 では IFS マネー
ジャと呼ばれます。VFS の役割は、要求を部分的に処理し、その要求の残りのサー
ビスを行う特定のファイルシステムを見つけることです。通常は、パス中の情報
は正しい FS ドライバを見つけるのに役立ちます。時として多くの前処理の後で、
VFS が FS ドライバがエクスポートしているルーチンの呼び出しを開始する場合
もあります。ここが要求のファイルシステム固有な処理を開始する地点で、ここ
で Coda 固有のカーネルコードが動き始めます。

<!--
The FS layer for Coda must expose and implement several interfaces.
First and foremost the VFS must be able to make all necessary calls to
the Coda FS layer, so the Coda FS driver must expose the VFS interface
as applicable in the operating system. These differ very significantly
among operating systems, but share features such as facilities to
read/write and create and remove objects.  The Coda FS layer services
such VFS requests by invoking on or more well defined services
offered by the cache manager Venus.  When the replies from Venus have
come back to the FS driver, servicing of the VFS call continues and
finishes with a reply to the kernels VFS. Finally the VFS layer
returns to the process. 
-->
<!--draft2-->
Coda 用 FS 層はいくつかのインターフェースを公開し実装しなければなりませ
ん。まず第一に、VFS は Coda FS 層への必要なコールをすべて行えなければな
らないので、Coda FS ドライバはオペレーティングシステムで使える形式で、
VFS インターフェースを公開しなければなりません。これらはオペレーティング
システム間で著しく異なりますが、オブジェクトを読む／書く、作成する、削除
する、ための機構といった機能で分かれます。Coda FS 層は、呼び出しによる
VFS 要求や、キャッシュマネージャ Venus から依頼される多くのかなり明確な
サービスを、サービスします。Venus からの応答が FS ドライバに返された場合、
VFS コールのサービスを続けて、カーネルの VFS への応答を伴い終了します。
最後に VFS 層はプロセスへ返ります。

<!--
As a result of this design a basic interface exposed by the FS driver
must allow Venus to manage message traffic.  In particular
Venus must be able to retrieve and place messages and to be notified
of the arrival of a new message. The notification must be through a
mechanism which does not block Venus since Venus must attend to
other tasks even when no messages are waiting or being processed.
-->
<!--draft2-->
この設計の結果、FS ドライバに公開された基本インターフェースは、メッセー
ジトラフィックの管理を Venus にさせるようにしなければなりません。特に
Venus はメッセージの受け取りおよび発行、新しいメッセージの到着の通知を受
けることができなければなりません。メッセージを待っていない場合やメッセー
ジを処理している場合でも、Venus は他のタスクに注意を払わなければならない
ので、通知は Venus をブロックしない仕組みになっていなければなりません。


<!--
<figure>
  <eps file="interfaces" height="7cm">
  <caption><label id="fig_overview">Interfaces of the Coda FS Driver
</figure>
-->

<!--
Furthermore the FS layer provides for a special path of communication
between a user process and Venus, called the pioctl interface. The
pioctl interface is used for Coda specific services, such as
requesting detailed information about the persistent cache managed by
Venus. Here the involvement of the kernel is minimal.  It identifies
the calling process and passes the information on to Venus.  When
Venus replies the response is passed back to the caller in unmodified
form. 
-->
さらに、FS 層は、ユーザプロセスと Venus 間の pioctl インターフェースと呼
ばれる特別なコミュニケーションパスを提供します。pioctl インターフェース
は、Venus に管理される永続的なキャッシュに関する詳細な情報を要求するよう
な、Coda 固有のサービスのために使われます。これはカーネルの関与を最小限
にします。呼び出しているプロセスを識別し、Venus へ情報を渡します。Venus
が応答する時、応答は修正されずに呼び出し元に返されます。

<!--
Finally Venus allows the kernel FS driver to cache the results from
certain services.  This is done to avoid excessive context switches
and results in an efficient system.  However, Venus may acquire
information, for example from the network which implies that cached
information must be flushed or replaced. Venus then makes a downcall
to the Coda FS layer to request flushes or updates in the cache.  The
kernel FS driver handles such requests synchronously. 
-->
<!--draft2-->
最後に、Venus は、カーネル FS ドライバが特定のサービスの結果をキャッシュ
することを許します。これは過度のコンテキストスイッチを回避させ、結果的に
効率的なシステムにしています。しかしながら、Venus は、例えばキャッシュさ
れた情報をフラッシュもしくは置きかえなければならないという情報をネットワー
クから得るかもしれません。そのような場合には Venus はキャッシュ内をフラッ
シュあるいは更新する要求を Coda FS 層に downcall します。カーネル FS ド
ライバはこのような要求を同期して扱います。

<!--
Among these interfaces the VFS interface and the facility to place,
receive and be notified of messages are platform specific.  We will
not go into the calls exported to the VFS layer but we will state the
requirements of the message exchange mechanism. 
-->
これらのインターフェースの中で、VFS インターフェースおよびメッセージを発
行、受け取る、通知を受ける機構はプラットフォーム固有です。VFS 層にエキス
ポートされたコールの説明は行いませんが、メッセージ交換の仕組みに必要なこ
とは述べます。

<!--
&newpage;<sect> The message layer <p>  
-->
<sect> メッセージ層 <p>

<!--
At the lowest level the communication between Venus and the FS driver
proceeds through messages.  The synchronization between processes
requesting Coda file service and Venus relies on blocking and waking
up processes.  The Coda FS driver processes VFS- and pioctl-requests
on behalf of a process P, creates messages for Venus, awaits replies
and finally returns to the caller.  The implementation of the exchange
of messages is platform specific, but the semantics have (so far)
appeared to be generally applicable.  Data buffers are created by the
FS Driver in kernel memory on behalf of P and copied to user memory in
Venus.
-->
<!--draft2-->
最下層では、Venus と FS ドライバ間のコミュニケーションはメッセージによっ
て進みます。Coda ファイルサービスを要求するプロセスと Venus 間の同期は
block (休止状態への移行) と wake (スケジュール待ち状態への移行) に依りま
す。Coda FS ドライバはプロセス P のために VFS および pioctl の要求を処理
し、Venus 向けのメッセージを作成し、応答を待ち、最後に呼び出し元に返りま
す。メッセージの交換の実装はプラットフォーム固有ですが、仕組みは一般的に
適用可能であると (今のところ) 考えています。プロセス P 用のためのデータ
バッファはカーネルメモリの中に FS ドライバによって作成され、Venus 内のユー
ザメモリにコピーされます。

<!--
The FS Driver while servicing P makes <tt>upcall</tt>'s to Venus.
Such an upcall is dispatched to Venus by creating a message structure.
The structure contains the identification of P, the message sequence
number, the size of the request and a pointer to the data in kernel
memory for the request.  Since the data buffer is re-used to hold the
reply from Venus, there is a field for the size of the reply.  A flags
field is used in the message to precisely record the status of the
message.  Additional platform dependent structures involve pointers to
determine the position of the message on queues and pointers to
synchronization objects.  In the <tt/upcall/ routine the message
structure is filled in, flags are set to 0, and it is placed on the
<em>pending</em> queue.  The routine calling <tt/upcall/ is
responsible for allocating the data buffer; it's structure will be
described in the next section.
-->
<!--draft2-->
P をサービスする間 FS ドライバは Venus への <tt>upcall</tt> を行います。
このような upcall はメッセージ構造体を作成することで、Venus へ送られます。
構造体は、P の識別子、メッセージシーケンス番号、要求のサイズおよび要求用
のカーネルメモリ内のデータへのポインタを含みます。データバッファは Venus
から応答を保持するために再利用されるので、返答のサイズ用のフィールドがあ
ります。フラグフィールドはメッセージの状態を正確に記録するためにメッセー
ジの中で使用されます。さらにプラットフォーム依存の構造体のメンバ (キュー
上のメッセージの位置を決めるポインタおよび同期化オブジェクトへのポインタ
など) があります。<tt/upcall/ ルーチンの中でメッセージ構造体の諸情報が記
入され、フラグは 0 に設定され、<em>待機</em>キューに置かれます。データバッ
ファの割当ては <tt/upcall/ を呼ぶルーチンの責任です - データバッファの構
造は次のセクションで説明します。

<!--
A facility must exist to notify Venus that the message has been
created, and implemented using available synchronization objects in
the OS. This notification is done in the <tt/upcall/ context of the
process P. When the message is on the pending queue, process P cannot
proceed in <tt/upcall/.  The (kernel mode) processing of P in the
filesystem request routine must be suspended until Venus has replied.
Therefore the calling thread in P is blocked in <tt/upcall/.  A
pointer in the message structure will locate the synchronization
object on which P is sleeping.
-->
<!--draft2-->
メッセージが作成されたことを通知する機構が存在し、かつ OS 内で利用可能な
同期化オブジェクトを用いて実装されていなければなりません。この通知はプロ
セス P の <tt/upcall/ コンテキストの中で行われます。メッセージが待機キュー
上にある時、プロセス P は <tt/upcall/ を行えません。ファイルシステム要求
ルーチン内の P の (カーネルモードの) 処理は、Venus が応答するまで、サス
ペンドされなければなりません。したがって、P からスレッドを呼ぼうとすると
<tt/upcall/ 中でブロックされます。メッセージ構造体のポインタは P をスリー
プさせている同期化オブジェクトを示すでしょう。

<!--
Venus detects the notification that a message has arrived, and the FS
driver allow Venus to retrieve the message with a
<tt>getmsg_from_kernel</tt> call. This action finishes in the kernel
by putting the message on the queue of processing messages and setting
flags to READ.  Venus is passed the contents of the data buffer. The
<tt/getmsg_from_kernel/ call now returns and Venus processes the
request.
-->
<!--draft2-->
Venus はメッセージが到着した通知を検出し、Venus は FS ドライバから
<tt>getmsg_from_kernel</tt> コールでメッセージを受け取ります。このコール
の処理はカーネル内で、処理するメッセージのキュー上にメッセージを置き、
READ のフラグを設定することで終わります。Venus にはデータバッファの内容
が渡されます。<tt/getmsg_from_kernel/ コールは呼び出し元に返り、Venus は
要求を処理します。

<!--
At some later point the FS driver receives a message from Venus,
namely when Venus calls <tt>sendmsg_to_kernel</tt>.  At this moment
the Coda FS driver looks at the contents of the message and decides
if:
-->
<!--draft2-->
すこししてから、FS ドライバは Venus からメッセージを受け取ります。具体的
には Venus が <tt>sendmsg_to_kernel</tt> をコールした際です。この時、
Coda FS ドライバはメッセージの内容を見て、以下の分類を行い何をするか決定
します -

<itemize>

<!--
<item> the message is a reply for a suspended thread P.  If so it
removes the message from the processing queue and marks the message as
WRITTEN.  Finally, the FS driver unblocks P (still in the kernel mode
context of Venus) and the <tt>sendmsg_to_kernel</tt> call returns to
Venus.  The process P will be scheduled at some point and continues
processing its <tt/upcall/ with the data buffer replaced with the
reply from Venus.
-->
<!--draft2-->
<item> メッセージがサスペンドされたスレッド P 向けの応答だった場合。この
場合、処理キューからメッセージを削除し、メッセージに WRITTEN とマークし
ます。最後に FS ドライバは (Venus のカーネルモードのコンテキスト中から)
P をアンブロックし、<tt>sendmsg_to_kernel</tt> コールは Venus に返ります。
プロセス P はその後スケジュールされ、Venus からの応答に置き換えられたデー
タバッファを用いて <tt/upcall/ の処理を続けます。

<!--
<item> The message is a <em>downcall</em>.  A downcall is a request
from Venus to the FS Driver. The FS driver processes the request
immediately (usually a cache eviction or replacement) and when finishes
<tt/sendmsg_to_kernel/ returns.
-->
<!--draft2-->
<item> メッセージは <em>downcall</em> の場合。downcall は Venus から FS
ドライバへの要求です。FS ドライバは要求を直ちに処理 (通常キャッシュの追
い立てか置き換え) し、終わった時、<tt/sendmsg_to_kernel/ は返ります。
</itemize>

<!--
Now P awakes and continues processing <tt/upcall/.  There are some
subtleties to take account off. First P will determine if it was woken
up in <tt/upcall/ by a signal from some other source (for example an
attempt to terminate P) or as is normally the case by Venus in its
<tt/sendmsg_to_kernel/ call.  In the normal case, the upcall routine
will deallocate message structure and return.  The FS routine can
proceed with its processing.
-->
<!--draft2-->
この後 P は起きて <tt/upcall/ の処理を続けます。説明の必要な微妙なことが
あります。始めに P は、他のソースからシグナルにより <tt/upcall/ の中で起
こされた (例えば P を終了しようとした) か、もしくは
<tt/sendmsg_to_kernel/ コールから戻ったことで普通に Venus により起こされ
たか、を決定することになります。通常の場合では、upcall を行ったルーチン
はメッセージ構造体を解放して返りますが、その際に FS ルーチンが
<tt/upcall/ 処理を続けることがあります。

<figure>
  <eps file="sleep">
  <caption><label id="ServerOrg"> Sleeping and IPC arrangements
</figure>

<!--
In case P is woken up by a signal and not by Venus, it will first look
at the flags field.  If the message is not yet READ, the process P can
handle it's signal without notifying Venus.  If Venus has READ, and
the request should not be processed, P can send Venus a signal message
to indicate that it should disregard the previous message.  Such
signals are put in the queue at the head, and read first by Venus.  If
the message is already marked as WRITTEN it is too late to stop the
processing.  The VFS routine will now continue. <footnote/If a VFS
request involves more than one upcall, this can lead to complicated
state, an extra field "handle_signals" could be added in the message
structure to indicate points of no return have been passed./
-->
<!--draft2-->
P が Venus ではなくシグナルによって起こされる場合、始めにフラグフィール
ドを見ます。メッセージがまだ READ でない場合、プロセス P は、Venus に通
知することなくそれを扱うことができます。Venus がそのメッセージをすでに読
んでおり (フラグが READ である)、要求を処理すべきではない場合、P は前の
メッセージを無視すべきことを示すシグナルメッセージを、Venus に送ることが
できます。このようなシグナルはキューの先頭に置かれ、Venus は始めに読みま
す。メッセージがすでに WRITTEN とマークされている場合、処理を止めるには
遅すぎます。VFS ルーチンはこの時点で続行します。<footnote/VFS 要求が二つ
以上の upcall を含む場合、これは複雑な状態になる可能性があります。この場
合の対処のため、すでに通過した返らない場所を示す特別なフィールド
&dquot;handle_signals&dquot; をメッセージ構造体に追加することができます。/

<!--
<sect1> Implementation details <p>
-->
<sect1> 実装の詳細 <p>
<!--TYPO implemenation は implementation-->
<!--
The Unix implementation of this mechanism has been through the
implemenation of a character device associated with Coda.  Venus
retrieves messages by doing a <tt/read/ on the device, replies are
sent with a <tt/write/ and notification is through the <tt/select/
system call on the file descriptor for the device.  The process P is
kept waiting on an interruptible wait queue object.
-->
<!--draft2-->
この仕組みの Unix 実装では、Coda に関連づけられたキャラクタデバイスが実
装されました。Venus はデバイスに<tt/読み取り/を行うことで、メッセージを
受け取り、応答は<tt/書き込み/で送られ、通知はデバイス用のファイル記述子
に対する <tt/select/ システムコールを用います。プロセス P は割込み可能な
待機キューのオブジェクト上で待たされます。

<!--TYPO asynchrounous は asynchronous-->
<!--
In Windows NT and the DPMI Windows 95 implementation a DeviceIoControl
call is used.  The DeviceIoControl call is designed to copy buffers
from user memory to kernel memory with OPCODES. The
<tt/sendmsg_to_kernel/ is issued as a synchronous call, while the
<tt/getmsg_from_kernel/ call is asynchrounous.  Windows EventObjects
are used for notification of message arrival.  The process P is kept
waiting on a KernelEvent object in NT and a semaphore in Windows 95. 
-->
<!--draft2-->
Windows NT および DPMI Windows 95 実装では DeviceIoControl コールが用い
られました。DeviceIoControl コールはユーザメモリからカーネルメモリへ
OPCODES でバッファをコピーするためのものです。<tt/sendmsg_to_kernel/ は
同期コールとして発行されますが、<tt/getmsg_from_kernel/ コールは非同期コー
ルです。Windows EventObjects がメッセージ到着の通知のために使われました。
プロセス P は、NT では KernelEvent オブジェクト、Windows 95 ではセマフォ
で待たされます。

<!--
&newpage;<sect> The interface at the call level <p>
-->
<sect> コールレベルのインターフェース <p>

<!--
This section describes the upcalls a Coda FS driver can make to Venus.
Each of these upcalls make use of three structures: <tt>
inputArgs</tt> for communication from kernel to Venus, and
<tt/outputArgs/ back from Venus to the kernel and finally downcalls
which are calls from Venus to the kernel initiated by Venus.  
-->
<!--draft2-->
このセクションは Coda FS ドライバが Venus に行える upcall について記述し
ます。これらそれぞれの upcall は三つの構造体を使用し行われます - カーネ
ルから Venus への通信用 <tt>inputArgs</tt>、Venus からカーネルに返る
<tt/outputArgs/、最後に <tt/cfs_downcalls/ で Venus からカーネルを起動す
る際に使われます。

<verb>
union inputArgs {
    struct cfs_in_hdr ih;	/* NB: every struct below begins with an ih */
    struct cfs_open_in cfs_open;
    struct cfs_close_in cfs_close;
    struct cfs_ioctl_in cfs_ioctl;
    struct cfs_getattr_in cfs_getattr;
    struct cfs_setattr_in cfs_setattr;
    struct cfs_access_in cfs_access;
    struct cfs_lookup_in cfs_lookup;
    struct cfs_create_in cfs_create;
    struct cfs_remove_in cfs_remove;
    struct cfs_link_in cfs_link;
    struct cfs_rename_in cfs_rename;
    struct cfs_mkdir_in cfs_mkdir;
    struct cfs_rmdir_in cfs_rmdir;
    struct cfs_readdir_in cfs_readdir;
    struct cfs_symlink_in cfs_symlink;
    struct cfs_readlink_in cfs_readlink;
    struct cfs_fsync_in cfs_fsync;
    struct cfs_inactive_in cfs_inactive;
    struct cfs_vget_in cfs_vget;
    struct cfs_rdwr_in cfs_rdwr;
    struct cfs_open_by_path_in cfs_open_by_path;
};
</verb>

<verb>
union outputArgs {
    struct cfs_out_hdr oh; /* NB: every struct below begins with an oh */
    struct cfs_root_out cfs_root;
    struct cfs_open_out cfs_open;
    struct cfs_ioctl_out cfs_ioctl;
    struct cfs_getattr_out cfs_getattr;
    struct cfs_lookup_out cfs_lookup;
    struct cfs_create_out cfs_create;
    struct cfs_mkdir_out cfs_mkdir;
    struct cfs_readdir_out cfs_readdir;
    struct cfs_readlink_out cfs_readlink;
    struct cfs_vget_out cfs_vget;
    struct cfs_purgeuser_out cfs_purgeuser;
    struct cfs_zapfile_out cfs_zapfile;
    struct cfs_zapdir_out cfs_zapdir;
    struct cfs_zapvnode_out cfs_zapvnode;
    struct cfs_purgefid_out cfs_purgefid;
    struct cfs_rdwr_out cfs_rdwr;
    struct cfs_replace_out cfs_replace;
    struct cfs_open_by_path_out cfs_open_by_path;
};
</verb>

<verb>
union cfs_downcalls {
    /* CFS_FLUSH  is also a down call */
    struct cfs_purgeuser_out purgeuser;
    struct cfs_zapfile_out zapfile;
    struct cfs_zapdir_out zapdir;
    struct cfs_zapvnode_out zapvnode;
    struct cfs_purgefid_out purgefid;
    struct cfs_replace_out replace;
};

</verb>

<!--
The headers are common to all calls and contain process, authentication and opcode information:
-->
ヘッダーはすべてのコールに共通で、プロセス、認証、opcode の情報を含みま
す -

<verb>
struct cfs_in_hdr {
    unsigned long opcode;
    unsigned long unique;    /* Keep multiple outstanding msgs distinct */
    u_short pid;		  /* Common to all */
    u_short pgid;		  /* Common to all */
    u_short sid;                  /* to become the PAG */
    struct coda_cred cred;	  /* to become a PAG */
};

/* Really important that opcode and unique are 1st two fields! */
struct cfs_out_hdr {
    unsigned long opcode;
    unsigned long unique;	
    unsigned long result;
};
</verb>

<!--
Before going on let us elucidate the role of the various fields. The
inputArgs start with the <tt/opcode/ which defines the type of service
requested from Venus. There are approximately 30 upcalls at present
which we will discuss.   The <tt/unique/ field labels the inputArg
with unique number which will identify the message uniquely.  A
process and process group id are passed.  Finally the credentials of
the caller are included.  
-->
<!--draft2-->
先に進む前に、様々なフィールドの役割を説明します。inputArgs は、Venus か
ら要求されるサービスの種類を定義した <tt/opcode/ で始まります。30 ほどの
upcall があり、後で説明します。<tt/unique/ フィールドはメッセージを一意
に識別するユニークな数で inputArg を識別します。プロセスおよびプロセスグ
ループの id も渡されます。最後に、呼び出し元の信頼度の情報が含まれます。

<!--
Before delving into the specific calls we need to discuss a variety of
data structures shared by the kernel and Venus.
-->
特定のコールを調べる前に、カーネルと Venus に共有される様々なデータ構造
体を知る必要があります。

<!--
<sect1> Data structures shared by the kernel and Venus <p>
-->
<sect1> カーネルと Venus に共有されるデータ構造体 <p>

<!--
The <tt/CodaCred/ structure defines a variety of user and group id's as
they are set for the calling process. The <tt/vuid_t/ and <tt/guid_t/
are 32 bit unsigned integers.  It also defines group member
ship in an array.  On Unix the CodaCred has proven sufficient to
implement good security semantics for Coda but the structure may have
to undergo modification for the Windows environment when these mature.
-->
<!--draft2-->
<tt/CodaCred/ 構造体は user および group id に関する様々なものを定義し、
呼び出し元のプロセスによって設定されます。<tt/vuid_t/ および <tt/guid_t/
は 32 ビット符号なし整数です。配列内の group メンバシップも定義します。
Unix 上では CodaCred は Coda 用のよいセキュリティの仕組みの実装に十分で
あると分かっていますが、Windows 環境でのセキュリティ環境の成熟にあわせた
構造体の修正をしなければならないかもしれません。
<verb>
struct CodaCred {
    vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, efftve, set, fs uid*/
    vgid_t cr_gid, cr_egid, cr_sgid, cr_fsgid; /* same for groups */
    vgid_t cr_groups[NGROUPS];	      /* Group membership for caller */
};
</verb>

<!--
<bf/NOTE/ It is questionable if we need CodaCreds in Venus. Finally
Venus doesn't know about groups, although it does create files with
the default uid/gid.  Perhaps the list of group membership is
superfluous. 
-->
<bf/注記/ Venus 内で CodaCreds が必要かどうかは、疑問です。最終的に、
Venus は デフォルトの uid/gid を持ったファイルを作成するとはいえ、Venus
は group について知りません。たぶん group メンバシップのリストは余分です。


<!--
The next item is the fundamental identifier used to identify Coda
files, the <tt/ViceFid/.  A fid of a file uniquely defines a file or
directory in the Coda filesystem within a <em>cell</em>.  <footnote>A
<em>cell</em> is a group of Coda servers acting under the aegis of a
single system control machine or SCM. See the Coda Administration
manual for a detailed description of the role of the SCM.</footnote>
-->
次のアイテムは Coda ファイルを識別するために使われる基本的な識別子
<tt/ViceFid/ です。ファイルの fid は <em>cell</em> 内の Coda ファイルシ
ステムのファイルもしくはディレクトリを一意的に定義します。
<footnote><em>cell</em> は単一の system control machine (SCM) の保護下で
稼動する Coda サーバのグループです。</footnote>

<verb>
typedef struct ViceFid {
    VolumeId Volume;
    VnodeId Vnode;
    Unique_t Unique;
} ViceFid;
</verb>

<!--
Each of the constituent fields: <tt/VolumeId, VnodeId/ and
<tt/Unique_t/ are unsigned 32 bit integers.  We envisage that a
further field will need to be prefixed to identify the Coda cell; this
will probably take the form of a Ipv6 size IP address naming the Coda
cell through DNS.  
-->
<!--draft2-->
構成中の各フィールド - <tt/VolumeId,VnodeId, Unique_t/ は符号なし 32 ビッ
ト整数です。Coda cell を識別するためにもう一つフィールドを前に付ける必要
があるだろうと考えています - これはたぶん、DNS によって Coda cell を指定
する Ipv6 サイズの IP アドレスの形式になるでしょう。

<!--
The next important structure shared between Venus and the kernel are
the attributes of the file.  The following structure is used to
exchange information.  It has room for future extensions such as
support for device files (currently not present in Coda). 
-->
Venus とカーネル間で共有された次に重要な構造体はファイルの属性です。続く
構造体は情報交換に使用されます。それはデバイスファイル向けのサポート (現
状 Coda にはありません) のような将来の拡張用の場所があります。

<verb>
struct coda_vattr {
	enum coda_vtype	va_type;	/* vnode type (for create) */
	u_short		va_mode;	/* files access mode and type */
	short		va_nlink;	/* number of references to file */
	vuid_t		va_uid;		/* owner user id */
	vgid_t		va_gid;		/* owner group id */
	long		va_fsid;	/* file system id (dev for now) */
	long		va_fileid;	/* file id */
	u_quad_t	va_size;	/* file size in bytes */
	long		va_blocksize;	/* blocksize preferred for i/o */
	struct timespec	va_atime;	/* time of last access */
	struct timespec	va_mtime;	/* time of last modification */
	struct timespec	va_ctime;	/* time file changed */
	u_long		va_gen;		/* generation number of file */
	u_long		va_flags;	/* flags defined for file */
	dev_t		va_rdev;	/* device special file represents */
	u_quad_t	va_bytes;	/* bytes of disk space held by file */
	u_quad_t	va_filerev;	/* file modification number */
	u_int		va_vaflags;	/* operations flags, see below */
	long		va_spare;	/* remain quad aligned */
};
</verb>

<!--
<sect1> The pioctl interface <p>
-->
<sect1> pioctl インターフェース <p>

<!--TYPO ficticious は fictious-->
<!--TYPO piocl は pioctl-->
<!--
Coda specific requests can be made by application through the pioctl
interface. The pioctl is implemented as an ordinary ioctl on a
ficticious file <tt>/coda/.CONTROL</tt>.  The piocl call opens this
file, gets a file handle and makes the ioctl call. Finally it closes
the file. 
-->
<!--draft2-->
Coda ファイルシステムに固有の要求を、pioctl インターフェースを介して、ア
プリケーションから行うことができます。pioctl は仮想ファイル
<tt>/coda/.CONTROL</tt> に対する普通の ioctl として実装されます。pioctl
コールはこのファイルを開き、ファイルハンドルを得て ioctl コールを行いま
す。最後にそのファイルを閉じます。

<!--
The kernel involvement in this is limited to providing the facility to
open and close and pass the ioctl message <em/and/ to verify that a
path in the pioctl data buffers is a file in a Coda filesystem.
-->
ここでのカーネルの関与は open, close, ioctl へのメッセージ渡し、pioctl
データバッファ内のパスが Coda ファイルシステムの中のファイルであることの
確認、の仕組みの提供に制限されます。

<!--
The kernel is handed a data packet of the form:
-->
カーネルは次の形式のデータパケットを渡されます -
<verb>
    struct {
	const char *path;
	struct ViceIoctl vidata;
	int follow;
    } data;
</verb>

<!--
where
-->
ここで

<verb>
struct ViceIoctl {
	caddr_t in, out;	/* Data to be transferred in, or out */
	short in_size;		/* Size of input buffer <= 2K */
	short out_size;		/* Maximum size of output buffer, <= 2K */
};
</verb>

<!--
The <tt/path/ must be a Coda file, otherwise the <tt/ioctl/ upcall
will not be made. 
-->
<tt/path/は Coda ファイルでなければならず、そうでなければ <tt/ioctl/
upcall は行われないでしょう。

<!--
<bf/NOTE/  The data structures and code are a mess.  We need to clean
this up. 
-->
<bf/注記/  データ構造体およびコードはむちゃくちゃです。これを整理する必
要があります。

<!--
We now proceed to document the individual calls:
-->
個々のコールを説明します -

<!--
&newpage;<sect1>root<p>
-->
<sect1>root<p>

<!--
<bf>Arguments</bf>
-->
<bf>引き数</bf>
<descrip>
<!--
<tag/in/ empty
<tag/out/ 
-->
<tag/入力/ 空
<tag/出力/ 
<verb>
	struct cfs_root_out {
	    ViceFid VFid;
	} cfs_root;
</verb>
</descrip>

<!--
<bf/Description/ This call is made to Venus during the initialization
of the Coda filesystem. If the <tt/result/ is zero, the <tt/cfs_root/
structure contains the ViceFid of the root of the Coda filesystem. If
a non-zero result is generated, its value is a platform dependent
error code indicating the difficulty Venus encountered in locating the
root of the Coda filesystem.
-->
<!--draft2-->
<bf/詳細/ このコールは Coda ファイルシステムの初期化中に Venus へ行われ
ます。<tt/結果/が 0 なら、<tt/cfs_root/ 構造体には Coda ファイルシステム
のルートの ViceFid が入っています。0 でない結果が生成される場合、その値
は Coda ファイルシステムのルートを見つける際に Venus が問題に出合ったこ
とを示すプラットフォームに依存したエラーコードです。

<!--
&newpage;<sect1>lookup<p>
-->
<sect1>lookup<p>

<!--
<bf/Summary/ Find the ViceFid and type of an object in a directory if
it exists.
-->
<bf/概要/ ディレクトリにその ViceFid およびオブジェクトの種別が存在する
か探します。

<!--
<bf>Arguments</bf>
-->
<bf>引き数</bf>
<descrip>
<!--
<tag/in/ 
-->
<tag/入力/
<verb>
	struct  cfs_lookup_in {
	    ViceFid	VFid;
	    char        *name;		/* Place holder for data. */
	} cfs_lookup;
</verb>
<!--
<tag/out/ 
-->
<tag/出力/ 
<verb>
	struct cfs_lookup_out {
	    ViceFid VFid;
	    int	vtype;
	} cfs_lookup;
</verb>
</descrip>

<!--
<bf/Description/ This call is made to determine the ViceFid and
filetype of a directory entry.  The directory entry requested carries
name <tt/name/ and Venus will search the directory identified by
<tt/cfs_lookup_in.VFid/.  The <tt/result/ may indicate that the name
does not exist, or that difficulty was encountered in finding it
(e.g. due to disconnection).  If the <tt/result/ is zero, the field
<tt/cfs_lookup_out.VFid/ contains the targets ViceFid and
<tt/cfs_lookup_out.vtype/ the <tt/coda_vtype/ giving the type of
object the name designates. 
-->
<!--draft2-->
<bf/詳細/ このコールはディレクトリエントリの ViceFid および filetype を
決めるために行われます。要求されたディレクトリエントリは <tt/name/ とい
う名前を持ち、Venus は <tt/cfs_lookup_in.VFid/ で指定されたディレクトリ
を検索するでしょう。<tt/結果/は、名前が存在しないか、それを見つける際に
問題に出合った (例えばコネクションが切れた) ことを示すかもしれません。
<tt/結果/が 0 なら、フィールド <tt/cfs_lookup_out.VFid/ は対象の ViceFid
が入り、<tt/cfs_lookup_out.vtype/ にはオブジェクトの種別を示す名前
<tt/coda_vtype/ が入ります。

<!--
The name of the object is an 8 bit character string of maximum length
CFS_MAXNAMLEN, currently set to 256 (including a 0 terminator.)
-->
<!--draft2-->
オブジェクトの名前は最大長 CFS_MAXNAMLEN の 8 ビット文字列で、現在
CFS_MAXNAMLEN は 256 に設定されています (文字数は 0 ターミネータ文字を含
みます)。

<!--
It is extremely important to realize that Venus bitwise or's the field
<tt/cfs_lookup.vtype/ with <tt/CFS_NOCACHE/ to indicate that the
object should not be put in the kernel name cache. Files in conflict or 
uncovered mountpoints should never be cached by the kernel and each lookup
should make it to Venus.
-->
<!--draft2-->
オブジェクトがカーネルのネームキャッシュに置かれてはならないことを示す
<tt/CFS_NOCACHE/ で、Venus がフィールド <tt/cfs_lookup.vtype/ をビット和
していることを理解することは非常に重要です。各ホストで競合するファイルや
Coda 管理下のファイルシステム内の実際のファイルはカーネルに決してキャッ
シュされてはならず、lookup は毎回 Venus に行われなければなりません。

<!--
<bf/NOTE/ The type of the vtype is currently wrong.  It should be
<tt/coda_vtype/. Linux does not take note of <tt/CFS_NOCACHE/.  It
should. 
-->
<!--draft2-->
<bf/注記/ vtype の種別は現状誤りです。<tt/coda_vtype/ になるべきです。
Linux は <tt/CFS_NOCACHE/ を属性を考慮しませんが、考慮すべきです。

<!--
&newpage;<sect1>getattr<p>
-->
<sect1>getattr<p>

<!--
<bf>Summary</bf> Get the attributes of a file.
-->
<bf>概要</bf> ファイルの属性を得ます。

<!--
<bf>Arguments</bf>
-->
<bf>引き数</bf>
<descrip>
<!--
<tag/in/ 
-->
<tag/入力/ 
<verb>
	struct cfs_getattr_in {
	    ViceFid VFid;
	    struct coda_vattr attr; /* XXXXX */
	} cfs_getattr;
</verb>
<!--
<tag/out/ 
-->
<tag/出力/ 
<verb>
	struct cfs_getattr_out {
	    struct coda_vattr attr;
	} cfs_getattr;
</verb>
</descrip>

<!--
<bf/Description/
This call returns the attributes of the file identified by fid. 
-->
<!--draft2-->
<bf/詳細/
このコールは fid で指定されたファイルの属性を返します。

<!--
<bf/Errors/ Errors can occur if the object with fid does not exist,
are unaccessible or if the caller does not have permission to fetch
attributes.
-->
<!--draft2-->
<bf/エラー/ fid を持ったオブジェクトが存在しないかアクセスできない場合や
呼び出し元に属性を見るパーミッションがない場合、エラーが起きる可能性があ
ります。

<!--TYPO Windows 95 の後に閉じ括弧がない-->
<!--
<bf/Note/ Many kernel FS drivers (Linux, NT and Windows 95 need to
acquire the attributes as well as the Fid for the instantiation of an
internal "inode" or "FileHandle".  A significant improvement in
performance on such systems could be made by combining the <em/lookup/
and <em/getattr/ calls both at the Venus/kernel interaction level and
at the RPC level. 
-->
<!--draft2-->
<bf/注記/ カーネル FS ドライバ (Linux、NT, Windows 95) の多くは、内部の
&dquot;inode&dquot; や &dquot;FileHandle&dquot; のインスタンスを作成する
ために、Fid だけでなく属性も得る必要があります。このようなシステムでは
Venus/カーネル相互作用レベルと RPC レベルの両方で、<em/lookup/ と
<em/getattr/ コールを組合わせることによってパフォーマンスを著しく向上で
きるかもしれません。

<!--
The <tt/vattr/ structure included in the input arguments is
superfluous and should be removed.
-->
入力の引き数内の <tt/vattr/ 構造体は余分で削除されるべきです。

<!--
&newpage;<sect1>setattr<p>
-->
<sect1>setattr<p>

<!--
<bf/Summary/ Set the attributes of a file.
-->
<bf/概要/ ファイルの属性を設定します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_setattr_in {
	    ViceFid VFid;
	    struct coda_vattr attr;
	} cfs_setattr;
</verb>
<!--
<tag/out/ empty
-->
<tag/出力/ 空
</descrip>

<!--
<bf/Description/ The structure <tt/attr/ is filled with attributes to
be changed in BSD style.  Attributes not to be changed are set to -1,
apart from <tt/vtype/ which is set to <tt/VNON/. Other are set to the
value to be assigned.  The only attributes which the FS driver may
request to change are the mode, ownner, groupid, atime, mtime and
ctime.  The return value indicates success or failure.
-->
<!--draft2-->
<bf/詳細/ 構造体 <tt/attr/ は BSD スタイルに変更された属性で記入されます。
<tt/VNON/ に設定される <tt/vtype/ 以外の変更されない属性は -1 に設定され
ます。他は指定された値に設定されます。ただし、FS ドライバが変更の要求を
行ってよい属性は、mode, ownner, groupid, atime, mtime, ctime だけです。
返り値は成功か失敗を示します。

<!--
<bf/Errors/ A variety of errors can occur.  The object may not exist,
may be inaccessible, or permission may not be granted by Venus.
-->
<bf/エラー/ 様々なエラーが起こる可能性があります。オブジェクトが存在しな
い、アクセスできない、パーミッションが Venus から与えられないなど。

<!--
&newpage;<sect1>access<p>
-->
<sect1>access<p>

<!--
<bf/Summary/
-->
<bf/概要/

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_access_in {
	    ViceFid	VFid;
	    int	flags;
	} cfs_access;
</verb>
<!--
<tag/out/ empty
-->
<tag/出力/ 空
</descrip>

<!--TYPO wether は whether-->
<!--
<bf/Description/ Verify if access to the object identified by <tt/VFid/ for
operations described by <tt/flags/ is permitted.  The result indicates
if access will be granted.  It is important to remember that Coda uses
ACL's to enforce protection and that ultimately the servers, not the
clients enforce the security of the system.  The result of this call
will depend on wether a <em/token/ is held by the user.
-->
<!--draft2-->
<bf/詳細/ <tt/flags/ に記載された操作を行うために、<tt/VFid/ で指定され
るオブジェクトのアクセス権が得られるかどうか確認をします。結果はアクセス
権の有無を示します。Coda は保護を強化するために ACL を使っており、結局の
ところクライアントではなくサーバがシステムのセキュリティを保証していると
いうことを知っておくことは重要です。このコールの結果は、ユーザが
<em/トークン/を保持しているかどうかに依存するでしょう。

<!--
<bf/Errors/ The object may not exist, or the ACL describing the
protection may not be accessible.
-->
<!--draft2-->
<bf/エラー/ オブジェクトは存在しないかもしれません、もしくは保護情報を記
載する ACL はアクセス可能ではないかもしれません。

<!--
&newpage;<sect1>create<p>
-->
<sect1>create<p>

<!--
<bf/Summary/ Invoked to create a file
-->
<bf/概要/ ファイルを作成するために呼び出されます。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_create_in {
	    ViceFid VFid;
	    struct coda_vattr attr;
	    int excl;
	    int mode;
	    char	*name;		/* Place holder for data. */
	} cfs_create;
</verb>
<!--
<tag/out/
-->
<tag/出力/
<verb>
	struct cfs_create_out {
	    ViceFid VFid;
	    struct coda_vattr attr;
	} cfs_create;

</verb>
</descrip>

<!--
<bf/Description/  This upcall is invoked to request creation of a
file.  The file will be created in the directory identified by
<tt/VFid/, its name will be <tt/name/, and the mode will be
<tt/mode/.  If <tt/excl/ is set an error will be returned if the file
already exists.  If the size field in attr is set to zero the file
will be truncated.  The uid and gid of the file are set by converting
the CodaCred to a uid using a macro <tt/CRTOUID/ (this macro is
platform dependent).  Upon success the VFid and attributes of the file
are returned.  The Coda FS Driver will normally instantiate a vnode,
inode or filehandle at kernel level for the new object. 
-->
<!--draft2-->
<bf/詳細/  この upcall はファイルの作成を要求するために呼び出されます。
ファイルは <tt/VFid/ で指定されたディレクトリの中に作成され、その名前は
<tt/name/、モードは <tt/mode/ になるでしょう。<tt/excl/ が設定された場合、
ファイルが既に存在すればエラーが返るでしょう。attr の size フィールドが
0 に設定された場合、ファイルは切りつめられます。ファイルの uid および
gid は CodaCred を変換し設定され、uid はマクロ <tt/CRTOUID/ が用いられま
す (このマクロはプラットフォームに依存します)。成功した場合、ファイルの
VFid および属性が返されます。Coda FS ドライバは通常カーネルレベルで新し
いオブジェクトのために vnode, inode もしくはファイルハンドルのインスタン
スを作成するでしょう。

<!--
<bf/Errors/ A variety of errors can occur. Permissions may be
insufficient. If the object exists and is not a file the error
<tt/EISDIR/ is returned under Unix.
-->
<bf/エラー/ 様々なエラーが起こる可能性があります。パーミッションは不十分
かもしれません。オブジェクトが存在しそれがファイルでない場合、Unix 下で
エラー <tt/EISDIR/ が返されます。

<!--
<bf/NOTE/ The packing of parameters is very inefficient and appears to
indicate confusion between the system call creat and the VFS operation
create. The VFS operation create is only called to create new
objects. This create call differs from the Unix one in that it is not
invoked to return a file descriptor. The trunctate and exclusive
options, together with the mode, could simply be part of the mode as
it is under Unix.  There should be no flags argument; this is used in
<tt/open/ (2) to return a filedescriptor for READ or WRITE mode.
-->
<!--draft2-->
<bf/注記/ パラメータの組みはとても非効率的で、システムコールの creat と
VFS 操作の create との混同を示したものと思われます。VFS 操作の create は
新しいオブジェクトの作成の際にだけコールされます。この create コールは
Unix のコールとは異なり、ファイルディスクリプタを返すために呼び出される
ことはありません。トランケートとイクスクルシブのオプション、およびモード
は、単に Unix 下でのモードの一部にできるはずです。フラグの引き数があるべ
きではありません - 現在これは、READ もしくは WRITE モード用のファイルディ
スクプリタを返すために <tt/open/ (2) で使われています。

<!--
The attributes of the directory should be returned too, since the size
and mtime changed.
-->
ディレクトリの属性も、size および mtime が変更されるので、返されるはずで
す。

<!--
&newpage;<sect1>mkdir<p>
-->
<sect1>mkdir<p>

<!--
<bf/Summary/ Create a new directory.
-->
<bf/概要/ 新しいディレクトリを作成します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_mkdir_in {
	    ViceFid	VFid;
	    struct coda_vattr attr;
	    char	*name;		/* Place holder for data. */
	} cfs_mkdir;
</verb>
<!--
<tag/out/
-->
<tag/出力/
<verb>
	struct cfs_mkdir_out {
	    ViceFid VFid;
	    struct coda_vattr attr;
	} cfs_mkdir;
</verb>
</descrip>

<!--
<bf/Description/ This call is similar to <tt/create/ but creates a
directory. Only the <tt/mode/ field in the input parameters is used
for creation.  Upon successful creation, the <tt/attr/ returned
contains the attributes of the new directory.  
-->
<bf/詳細/ このコールは <tt/create/ に似ていますが、ディレクトリを作成し
ます。入力パラメータの <tt/mode/ フィールドだけが作成のために使われます。
作成が成功した場合、返される <tt/attr/ は新しいディレクトリの属性を持ち
ます。

<!--
<bf/Errors/ As for create.
-->
<bf/エラー/ create と同様です。

<!--
<bf/NOTE/ The input parameter should be changed to <tt/mode/ instead
of attributes. 
-->
<bf/注記/ 入力パラメータは属性の変わりに <tt/mode/ へ変更されるはずです。

<!--
The attributes of the parent should be returned since the size and
mtime changes.
-->
親の属性は、size および mtime が変わるので、返されるはずです。

<!--
&newpage;<sect1>link<p>
-->
<sect1>link<p>

<!--
<bf/Summary/ Create a link to an existing file.
-->
<bf/概要/ 既存ファイルへのリンクを作成します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_link_in {
	    ViceFid sourceFid;          /* cnode to link *to* */
	    ViceFid destFid;            /* Directory in which to place link */
	    char	*tname;		/* Place holder for data. */
	} cfs_link;
</verb>
<!--
<tag/out/ empty
-->
<tag/出力/ 空
</descrip>

<!--
<bf/Description/ This call creates a link to the <tt/sourceFid/ in the
directory identified by <tt/destFid/ with name <tt/tname/.  The source
must reside in the targets parent, i.e. the source must be have parent
<tt/destFid/, i.e. Coda does not support cross directory hard links.
Only the return value is relevant.  It indicates success or the type
of failure.
-->
<!--draft2-->
<bf/詳細/ このコールは、名前 <tt/tname/ を持った <tt/destFid/ で指定され
るディレクトリの中に <tt/sourceFid/ へのリンクを作成します。ソースはター
ゲットの親ディレクトリ内に存在しなければなりません。つまり、ソースの親ディ
レクトリは <tt/destFid/ でなければなりません。つまり Coda はディレクトリ
をまたいだハードリンクをサポートしていません。返り値は関連するものだけで
す。それは成功もしくは失敗の種別を示します。

<!--
<bf/Errors/ The usual errors can occur.
-->
<!--draft2-->
<bf/エラー/ 通常のエラーが起こる可能性があります。
<!--
&newpage;<sect1>symlink<p>
-->
<sect1>symlink<p>

<!--
<bf/Summary/ create a symbolic link
-->
<bf/概要/ シンボリックリンクを作成します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_symlink_in {
	    ViceFid	VFid;          /* Directory to put symlink in */
	    char	*srcname;
	    struct coda_vattr attr;
	    char	*tname;
	} cfs_symlink;
</verb>
<!--
<tag/out/ none
-->
<tag/出力/ なし
</descrip>

<!--
<bf/Description/ Create a symbolic link. The link is to be placed in
the directory identified by <tt/VFid/ and named <tt/tname/.  It should
point to the pathname <tt/srcname/.  The attributes of the newly
created object are to be set to <tt/attr/.
-->
<!--draft2-->
<bf/詳細/ シンボリックリンクを作成します。リンクは <tt/VFid/ で指定され
るディレクトリに置かれ、<tt/tname/ の名前になります。それはパス名
<tt/srcname/ を指すはずです。新しく作成されたオブジェクトの属性は
<tt/attr/ が設定されます。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ The attributes of the target directory should be returned
since its size changed. 
-->
<bf/注記/ ターゲットディレクトリの属性は、size が変更されるので、返され
るはずです。

<!--
&newpage;<sect1>remove<p>
-->
<sect1>remove<p>

<!--
<bf/Summary/ Remove a file
-->
<bf/概要/ ファイルを削除します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_remove_in {
	    ViceFid	VFid;
	    char	*name;		/* Place holder for data. */
	} cfs_remove;
</verb>
<!--
<tag/out/ none
-->
<tag/出力/ なし
</descrip>

<!--
<bf/Description/  Remove file named <tt/cfs_remove_in.name/ in
directory identified by   <tt/VFid/. 
-->
<!--draft2-->
<bf/詳細/  <tt/VFid/ で指定されるディレクトリの中の
<tt/cfs_remove_in.name/ で指定されたファイルを削除します。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ The attributes of the directory should be returned since its
mtime and size may change.
-->
<bf/注記/ ディレクトリの属性は、size および mtime が変わるかもしれないの
で、返されるはずです。

<!--
&newpage;<sect1>rmdir<p>
-->
<sect1>rmdir<p>

<!--
<bf/Summary/ Remove a directory
-->
<bf/概要/ ディレクトリを削除します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_rmdir_in {
	    ViceFid	VFid;
	    char	*name;		/* Place holder for data. */
	} cfs_rmdir;
</verb>
<!--
<tag/out/ none
-->
<tag/出力/ なし
</descrip>

<!--
<bf/Description/ Remove the directory with name <tt/name/ from the
directory identified by <tt/VFid/.
-->
<!--draft2-->
<bf/詳細/ <tt/VFid/ で指定されるディレクトリから <tt/name/ で指定された
ディレクトリを削除します。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ The attributes of the parent directory should be returned
since its mtime and size may change. 
-->
<bf/注記/ 親ディレクトリの属性は、size および mtime が変わるかもしれない
ので、返されるはずです。

<!--
&newpage;<sect1>readlink<p>
-->
<sect1>readlink<p>

<!--
<bf/Summary/ Read the value of a symbolic link.
-->
<bf/概要/ シンボリックリンクの値を読み出します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_readlink_in {
	    ViceFid VFid;
	} cfs_readlink;
</verb>
<!--
<tag/out/
-->
<tag/出力/
<verb>
	struct cfs_readlink_out {
	    int	count;
	    caddr_t	data;		/* Place holder for data. */
	} cfs_readlink;
</verb>
</descrip>

<!--
<bf/Description/ This routine reads the contents of symbolic link
identified by <tt/VFid/ into the buffer <tt/data/.  The buffer
<tt/data/ must be able to hold any name up to <tt/CFS_MAXNAMLEN/ (PATH or
NAM??). 
-->
<bf/詳細/ このルーチンは <tt/VFid/ で指定されるシンボリックリンクの内容
をバッファ <tt/data/ の中に読み出します。バッファ <tt/data/ はどんな名前
でも保持できるように <tt/CFS_MAXNAMLEN/ の大きさが必要です (PATH もしく
は NAME??)。

<!--
<bf/Errors/ No unusual errors.
-->
<!--draft2-->
<bf/エラー/ 通常のエラーだけです。

<!--
&newpage;<sect1>open<p>
-->
<sect1>open<p>

<!--
<bf/Summary/ Open a file.
-->
<bf/概要/ ファイルを開きます。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_open_in {
	    ViceFid	VFid;
	    int	flags;
	} cfs_open;
</verb>
<!--
<tag/out/
-->
<tag/出力/
<verb>
	struct cfs_open_out {
	    dev_t	dev;
	    ino_t	inode;
	} cfs_open;
</verb>
</descrip>

<!--
<bf/Description/  This request asks Venus to place the file identified
by <tt/VFid/ in its cache and to note that the calling process wishes
to open it with <tt/flags/ as in <tt/open(2)/.  The return value to
the kernel differs for Unix and Windows systems.  For Unix systems the
Coda FS Driver is informed of the device and inode number of the
container file in the fields <tt/dev/ and <tt/inode/.  For Windows the
path of the container file is returned to the kernel. 
-->
<!--draft2-->
<bf/詳細/  これは <tt/VFid/ で指定されるファイルを Venus のキャッシュに
置くよう Venus に依頼し、次に呼び出し元のプロセスが <tt/open(2)/ の
<tt/flags/ の値でそのキャッシュ内のファイルを開くよう指定する一連の要求
です。カーネルへの返り値は Unix と Windows システムでは異なります。Unix
システムでは Coda FS ドライバは <tt/dev/ および <tt/inode/ のフィールド
の中のコンテナファイルのデバイスおよび inode の番号を通知されます。
Windows では、コンテナファイルのパスがカーネルに返されます。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ Currently the <tt/cfs_open_out/ structure is not properly
adapted to deal with the windows case.  It might be best to implement
two upcalls, one to open aiming at a container file name, the other at
a container file inode. 
-->
<!--draft2-->
<bf/注記/ 現状、<tt/cfs_open_out/ 構造体は Windows 環境での操作と厳密に
は整合性がとれていません。一つはコンテナファイルの名前で開く、もう一つは
コンテナファイルの inode で開く、という二つの upcall を実装することが最
良かもしれません。

<!--
&newpage;<sect1>close<p>
-->
<sect1>close<p>

<!--
<bf/Summary/ Close a file, update it on the servers.
-->
<bf/概要/ ファイルを閉じ、サーバ上でそれを更新します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_close_in {
	    ViceFid	VFid;
	    int	flags;
	} cfs_close;
</verb>
<!--
<tag/out/ none
-->
<tag/出力/ なし
</descrip>

<!--
<bf/Description/ Close the file identified by <tt/VFid/.  
-->
<!--draft2-->
<bf/詳細/  <tt/VFid/ で指定されるファイルを閉じます。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ The <tt/flags/ argument is bogus and not used.  However,
Venus' code has room to deal with an <tt/execp/ input field, probably
this field should be used to inform Venus that the file was closed but
is still memory mapped for execution.  There are comments about
fetching versus not fetching the data in Venus <tt/vproc_vfscalls/.
This seems silly.  If a file is being closed, the data in the
container file is to be the new data.  Here again the <tt/execp/ flag
might be in play to create confusion: presently Venus might think a
file can be flushed from the cache when it is still memory mapped.
This needs to be understood.
-->
<!--draft2-->
<bf/注記/ <tt/flags/ 引き数は無意味で、使用されません。しかしながら、
Venus のコードは <tt/execp/ 入力フィールドを扱う余地があり、たぶん、この
フィールドは、ファイルは閉じられたが実行のためにメモリにマップされたまま
であることを、Venus に通知するために使われることになるはずです。Venus
<tt/vproc_vfscalls/ でデータを取ってくることおよび取ってこないことについ
ての注釈があります。これは変です。ファイルが閉じられている場合、コンテナ
ファイルの中のデータは新しいデータになっているとすべきだからです。ここで
も <tt/execp/ フラグは混乱の元になっているかもしれません - 現在の Venus 
ではファイルが静的なメモリにマップされているのにもかかわらず、ファイルを
キャッシュからフラッシュできると考えるかもしれません。このことを理解する
必要があります。

<!--
&newpage;<sect1>ioctl<p>
-->
<sect1>ioctl<p>

<!--TYPO piocl は pioctl-->
<!--
<bf/Summary/ Do an ioctl on a file. This includes the piocl interface.
-->
<bf/概要/ ファイルに対する ioctl を行います。これは pioctl インターフェー
スを含みます。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_ioctl_in {
	    ViceFid VFid;
	    int	cmd;
	    int	len;
	    int	rwflag;
	    char *data;			/* Place holder for data. */
	} cfs_ioctl;
</verb>
<!--
<tag/out/
-->
<tag/出力/
<verb>
	struct cfs_ioctl_out {
	    int	len;
	    caddr_t	data;		/* Place holder for data. */
	} cfs_ioctl;
</verb>
</descrip>

<!--
<bf/Description/ Do an ioctl operation on a file.  The <tt/command,
len/ and <tt/data/ arguments are filled as usual.  <tt/flags/ is not
used by Venus. 
-->
<bf/詳細/ ファイルに対する ioctl 操作を行います。 <tt/command, len,
data/ 引き数は通常記載されます。<tt/flags/ を Venus は使用しません。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ Another bogus parameter.  <tt/flags/ is not used.  What is
the business about PREFETCHING in the Venus' code?
-->
<!--draft2-->
<bf/注記/ ここでも無用なパラメータです。<tt/flags/ は使われません。Venus
のコード中の PREFETCHING を何に使おうと言うつもりなんでしょう ?


<!--
&newpage;<sect1>rename<p>
-->
<sect1>rename<p>

<!--
<bf/Summary/ Rename a fid.
-->
<bf/概要/ fid の名前を変更します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_rename_in {
	    ViceFid	sourceFid;
	    char	*srcname;
	    ViceFid destFid;
	    char	*destname;
	} cfs_rename;

</verb>
<!--
<tag/out/ none
-->
<tag/出力/ なし
</descrip>

<!--
<bf/Description/  Rename the object with name <tt/srcname/ in
directory <tt/sourceFid/ to <tt/destname/ in <tt/destFid/.   It is
important that the names <tt/srcname/ and <tt/destname/ are 0
terminated strings.  Strings in Unix kernels are not always null
terminated. 
-->
<bf/詳細/  ディレクトリ <tt/sourceFid/ の中の <tt/srcname/ という名前の
オブジェクトを <tt/destFid/ の中の <tt/destname/ に変更します。名前
<tt/srcname/ および <tt/destname/ の文字列は 0 でターミネートしてくださ
い。Unix カーネルにおける文字列はいつも null ターミネートされているとは
限りません。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
&newpage;<sect1>readdir<p>
-->
<sect1>readdir<p>

<!--
<bf/Summary/ Read directory entries.
-->
<bf/概要/ ディレクトリエントリを読み出します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_readdir_in {
	    ViceFid	VFid;
	    int	count;
	    int	offset;
	} cfs_readdir;
</verb>
<!--
<tag/out/
-->
<tag/出力/
<verb>
	struct cfs_readdir_out {
	    int	size;
	    caddr_t	data;		/* Place holder for data. */
	} cfs_readdir;
</verb>
</descrip>

<!--
<bf/Description/ Read directory entries from <tt/VFid/ starting at
<tt/offset/ and read at most <tt/count/ bytes.  Returns the data
into <tt/data/ and indicates the size returned <tt/size/.
-->
<!--draft2-->
<bf/詳細/ ディレクトリエントリを <tt/VFid/ の <tt/offset/ から最大
<tt/count/ バイト読み出します。データは <tt/data/ の中に返され、そのサイ
ズを示す <tt/size/ が返ります。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ This call is not used.  Readdir operations exploit container
files.  We will re-evaluate this during the directory revamp which is
about to take place. 
-->
<!--draft2-->
<bf/注記/ このコールは使用されません。Readdir 操作はコンテナファイルを消
費するためです。これから行うディレクトリの改良の間に、この件を再考します。


<!--
&newpage;<sect1>vget<p>
-->
<sect1>vget<p>

<!--
<bf/Summary/ instructs Venus to do an <tt/FSDB->Get/.
-->
<bf/概要/ <tt/FSDB->Get/ を行うよう Venus に指示します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_vget_in {
	    ViceFid VFid;
	} cfs_vget;
</verb>
<!--
<tag/out/
-->
<tag/出力/
<verb>
	struct cfs_vget_out {
	    ViceFid VFid;
	    int	vtype;
	} cfs_vget;
</verb>
</descrip>

<!--
<bf/Description/ This upcall asks Venus to do a <tt/get/ operation on
an <tt/fsobj/ labelled by <tt/VFid/. 
-->
<bf/詳細/ この upcall は <tt/VFid/ でラベル付けされた <tt/fsobj/ に対し
て、<tt/get/ 操作を行うよう Venus に依頼します。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ This operation is not used.  However, it is extremely useful
since it can be used to deal with read/write memory mapped files.
These can be "pinned" in the Venus cache using <tt/vget/ and release
with <tt/inactive/.
-->
<bf/注記/ この操作は使用されません。しかしながら、メモリにマップされたファ
イルの読み出し／書き込みに対応するために使うことができるので、非常に有用
です。これらのファイルは <tt/vget/ を使用して Venus のキャッシュの中に
「固定」でき、<tt/inactive/ で解放できます。

<!--
&newpage;<sect1>fsync<p>
-->
<sect1>fsync<p>

<!--
<bf/Summary/ Tell Venus to update the RVM attributes of a file. 
-->
<bf/概要/ ファイルの RVM 属性を更新するよう Venus に命じます。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_fsync_in {
	    ViceFid VFid;
	} cfs_fsync;
</verb>
<!--
<tag/out/ none
-->
<tag/出力/ なし
</descrip>

<!--
<bf/Description/  Ask Venus to update RVM attributes of object
<tt/VFid/. This should be called as  part of kernel level <tt/fsync/
type calls.  The <tt/result/ indicates if the synching was
successful. 
-->
<bf/詳細/  オブジェクト <tt/VFid/ の RVM 属性を更新するよう Venus に依頼
します。これはカーネルレベルの <tt/fsync/ の類いのコールの一部として呼ば
れるはずです。<tt/結果/は同期が成功したかどうかを示します。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ Linux does not implement this call. It should. 
-->
<!--draft2-->
<bf/NOTE/ Linux はこのコールを実装していません。実装すべきです

<!--
&newpage;<sect1>inactive<p>
-->
<sect1>inactive<p>

<!--
<bf/Summary/ Tell Venus a vnode is no longer in use. 
-->
<bf/概要/ vnode をもう使用しないと Venus に命じます。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_inactive_in {
	    ViceFid VFid;
	} cfs_inactive;
</verb>
<!--
<tag/out/ none
-->
<tag/出力/ なし
</descrip>

<!--
<bf/Description/ This operation returns <tt/EOPNOTSUPP/.  
-->
<bf/詳細/ この操作は <tt/EOPNOTSUPP/ が返ります。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ This should perhaps be removed. 
-->
<bf/注記/ これはたぶん削除されるはずです。

<!--
&newpage;<sect1>rdwr<p>
-->
<sect1>rdwr<p>

<!--
<bf/Summary/ Read or write from a file
-->
<bf/概要/ ファイルに対し読み出しか書き込みをします。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct cfs_rdwr_in {
	    ViceFid	VFid;
	    int	rwflag;
	    int	count;
	    int	offset;
	    int	ioflag;
	    caddr_t	data;		/* Place holder for data. */	
	} cfs_rdwr;
</verb>
<!--
<tag/out/
-->
<tag/出力/
<verb>
	struct cfs_rdwr_out {
	    int	rwflag;
	    int	count;
	    caddr_t	data;	/* Place holder for data. */
	} cfs_rdwr;
</verb>
</descrip>

<!--
<bf/Description/ This upcall asks Venus to read or write from a file.
-->
<bf/詳細/ この upcall はファイルに対し読み出しか書き込みを行うよう Venus
に依頼します。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ It should be removed since it is against the Coda philosophy that
read/write operations never reach Venus.  I have been told the
operation does not work.  It is not currently used.
-->
<!--draft2-->
<bf/注記/ 読み出し／書き込みの操作を Venus は行わないという Coda の主義
に逆らうことなので、これは削除されるはずです。この操作は動作しないと聞い
ています。現在使用されていません。


<!--
&newpage;<sect1>odymount<p>
-->
<sect1>odymount<p>

<!--
<bf/Summary/ Allows mounting multiple Coda "filesystems" on one Unix mount
point.
-->
<bf/概要/ 一つの Unix のマウントポイントに複数の Coda ファイルシステムを
マウントすることを可能とします。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/
-->
<tag/入力/
<verb>
	struct ody_mount_in {
	    char	*name;		/* Place holder for data. */
	} ody_mount;
</verb>
<!--
<tag/out/
-->
<tag/出力/
<verb>
	struct ody_mount_out {
	    ViceFid VFid;
	} ody_mount;
</verb>
</descrip>

<!--
<bf/Description/  Asks Venus to return the rootfid of a Coda system
named <tt/name/.  The fid is returned in <tt/VFid/. 
-->
<bf/詳細/  <tt/name/ で指定された Coda システムの rootfid を返すよう
Venus に依頼します。fid は <tt/VFid/ の中に返されます。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ This call was used by David for dynamic sets.  It should be
removed since it causes a jungle of pointers in the VFS mounting area.
It is not used by Coda proper.  Call is not implemented by Venus. 
-->
<!--draft2-->
<bf/注記/ このコールは dynamic set 向けに David が使っていました。これは
VFS マウンティング領域のポインタを複雑にしてしまうので、削除されるはずで
す。普通の Coda は使用しません。このコールは Venus では実装されていませ
ん。

<!--
&newpage;<sect1>ody_lookup<p>
-->
<sect1>ody_lookup<p>

<!--
<bf/Summary/ Looks up something. 
-->
<bf/概要/ 何かを調べます。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/ irrelevant
<tag/out/ irrelevant
-->
<tag/入力/ 無関係
<tag/出力/ 無関係
</descrip>

<!--
<bf/Description/
-->
<bf/詳細/

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ Gut it. Call is not implemented by Venus. 
-->
<!--draft2-->
<bf/注記/ 中身はありません。このコールは Venus では実装されていません。

<!--
&newpage;<sect1>ody_expand<p>
-->
<sect1>ody_expand<p>

<!--
<bf/Summary/ expands something in a dynamic set.
-->
<bf/概要/ dynamic set における何かを拡張します。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/ irrelevant
<tag/out/ irrelevant
-->
<tag/入力/ 無関係
<tag/出力/ 無関係
</descrip>

<!--
<bf/Description/
-->
<bf/詳細/

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ Gut it.  Call is not implemented by Venus. 
-->
<!--draft2-->
<bf/注記/ 中身はありません。このコールは Venus では実装されていません。

<!--
&newpage;<sect1>prefetch<p>
-->
<sect1>prefetch<p>

<!--
<bf/Summary/ Prefetch a dynamic set.
-->
<bf/概要/ dynamic set を先読みします。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/ Not documented.
<tag/out/ Not documented.
-->
<!--draft2-->
<tag/入力/ ドキュメント化されていません。
<tag/出力/ ドキュメント化されていません。
</descrip>

<!--
<bf/Description/  Venus worker.cc has support for this call, although
it is noted that it doesn't work.  Not surprising, since the kernel
does not have support for it. (ODY_PREFETCH is not a defined
operation). 
-->
<!--draft2-->
<bf/詳細/  Venus の worker.cc にはこのコールのサポートがありますが、動作
しないと記されています。カーネルはサポートしていませんので、これは驚くべ
きことではありません (ODY_PREFETCH は動作が定義されていません)。

<!--
<bf/Errors/
-->
<bf/エラー/

<!--
<bf/NOTE/ Gut it. It isn't working and isn't used by Coda. 
-->
<bf/注記/ 中身はありません。コールは動作せず、Coda で使用されません。


<!--
&newpage;<sect1>signal<p>
-->
<sect1>signal<p>

<!--
<bf/Summary/ Send Venus a signal about an upcall. 
-->
<bf/概要/ upcall に関する signal を Venus に送ります。

<!--
<bf/Arguments/
-->
<bf/引き数/
<descrip>
<!--
<tag/in/ none
<tag/out/ not applicable.
-->
<tag/入力/ なし
<tag/出力/ 非適用
</descrip>

<!--
<bf/Description/  This is an out-of-band upcall to Venus to inform
Venus that the calling process received a signal after Venus read the
message from the input queue.  Venus is supposed to clean up the
operation.  
-->
<!--draft2-->
<bf/詳細/  これは Venus への upcall の通常処理範囲外のもので、Venus が入
力キューからメッセージを読んだ後、呼び出し元のプロセスが signal を受け取っ
たことを Venus に通知します。Venus は操作を完了することになっています。

<!--
<bf/Errors/ No reply is given.
-->
<bf/エラー/ 応答はありません。

<!--
<bf/NOTE/ We need to better understand what Venus needs to clean up
and if it is doing this correctly.  Also we need to handle multiple
upcall per system call situations correctly.  It would be important to
know what state changes in Venus take place after an upcall for which
the kernel is responsible for notifying Venus to clean up (e.g. open
definitely is such a state change, but many others are maybe not). 
-->
<!--draft2-->
<bf/注記/ Venus の完了処理を正しく行うために Venus が何を完了する必要が
あるのかを良く理解しておく必要があります。さらに、システムコールの状態毎
に複数の upcall を正確に扱う必要があります。また、Venus で upcall の後、
カーネルから (責任範囲として) 完了の通知を行う必要のあるどのような状態が
Venus で起きるのかを知ることが重要です (例えば open は間違いなくこのよう
な状態変化ですが、他の多くのものはそうではないかもしれません)。

<!--
&newpage;<sect> The minicache and downcalls <p>
-->
<sect> ミニキャッシュと downcall <p>

<!--
The Coda FS Driver can cache results of <tt/lookup/ and <tt/access/
upcalls, to limit the frequency of upcalls.  Upcalls carry a price
since a process context switch needs to take place.  The counterpart
of caching the information is that Venus will notify the FS Driver
that cached entries must be flushed or renamed.
-->
<!--draft2-->
Coda FS ドライバは、upcall の回数を抑制するために、<tt/lookup/ および
<tt/access/ の結果をキャッシュできます。upcall は、プロセスコンテキスト
スイッチを行う必要があるので、コストがかかります。情報をキャッシュするこ
とに対応して、Venus から FS ドライバにキャッシュされたエントリのフラッシュ
や名前の変更を行わなければならないという通知が行われます。

<!--
The kernel code generally has to maintain a structure which links the
internal file handles (called vnodes in BSD, inodes in Linux and
FileHandles in Windows) with the ViceFid's which Venus maintains.
The reason is that frequent translations back and forth are needed in
order to make upcalls and use the results of upcalls.  Such linking
objects are called <bf/cnodes/.
-->
<!--draft2-->
一般的にカーネルコードは、Venus が管理する ViceFid と共に内部のファイル
ハンドル (BSD で vnode, Linux で inode, Windows で FileHandle と呼ばれま
す) にリンクした構造体を管理しなければなりません。その理由は、頻繁な双方
向の変換が、upcall を行ったり、その upcall の結果を使用する際必要となる
からです。こういったリンクされたオブジェクトは <bf/cnode/ と呼ばれます。

<!--
The current minicache implementations have cache entries which record
the following:
-->
現行のミニキャッシュの実装は以下を記録したキャッシュエントリになっていま
す -
<enum>
<!--
<item> the name of the file
<item> the cnode of the directory containing the object
<item> a list of CodaCred's for which the lookup is permitted.
<item> the cnode of the object
-->
<item> ファイルの名前
<item> オブジェクトを含んでいるディレクトリの cnode
<item> lookup が許される CodaCred の一覧
<item> オブジェクトの cnode
</enum>

<!--
The <tt/lookup/ call in the Coda FS Driver may request the cnode of
the desired object from the cache, by passing it's name, directory and
the CodaCred's of the caller.  The cache will return the cnode or
indicate that it cannot be found.  The Coda FS Driver must be careful
to invalidate cache entries when it modifies or removes objects.
-->
<!--draft2-->
Coda FS ドライバにおける <tt/lookup/ コールは、呼び出し元の名前、ディレ
クトリ、CodaCred を渡し、キャッシュから希望するオブジェクトの cnode を要
求するかもしれません。キャッシュは cnode を返すか、見つからなかったこと
を示すでしょう。Coda FS ドライバは、オブジェクトの修正もしくは削除をした
場合、キャッシュエントリが無効になるように、気を付けなければなりません。

<!--
When Venus obtains information that indicates that cache entries are
no longer valid, it will make a downcall to the kernel.  Downcalls are
intercepted by the Coda FS Driver and lead to cache invalidations of
the kind described below.  The Coda FS Driver does not return an error
unless the downcall data could not be read into kernel memory. 
-->
キャッシュエントリがもう有効ではないことを示す情報を得た場合、Venus はカー
ネルに downcall を発行するでしょう。downcall は Coda FS ドライバに捕獲さ
れ、キャッシュを以下に述べる種類で無効にします。downcall のデータがカー
ネルメモリ内に読み出せない場合を除き、Coda FS ドライバはエラーを返しませ
ん。

<sect1>INVALIDATE<p>

<!--
No information is available on this call. 
-->
このコールの情報はありません。

<sect1>FLUSH<p>

<!--
<bf/Arguments/ None
-->
<bf/引き数/ なし
 
<!--
<bf/Summary/ Flush the name cache entirely.
-->
<bf/概要/ ネームキャッシュ全体をフラッシュします。

<!--
<bf/Description/ Venus issues this call upon startup and when it
dies. This is to prevent stale cache information being held.  Some
operating systems allow the kernel name cache to be switched off
dynamically. When this is done, this downcall is made. 
-->
<!--draft2-->
<bf/詳細/ Venus は起動時および終了時にこのコールを発行します。無効なキャッ
シュ情報の保持を防ぎます。カーネルのネームキャッシュを動的に切れるオペレー
ティングシステムもあります。これが終了した時 downcall は終了します。

<sect1> PURGEUSER<p>

<!--
<bf/Arguments/
-->
<bf/引き数/
<verb>
	struct cfs_purgeuser_out {/* CFS_PURGEUSER is a venus->kernel call */
	    struct CodaCred cred;
	} cfs_purgeuser;
</verb>

<!--TYPO tokes は token-->
<!--
<bf/Description/ Remove all entries in the cache carrying the Cred.
This call is issued when tokes for a user expire or are flushed.
-->
<!--draft2-->
<bf/詳細/ Cred を持つキャッシュ内のすべてのエントリを削除します。このコー
ルは、ユーザ用のトークンの期限が切れるかフラッシュされる時に発行されます。

<sect1>ZAPFILE<p>

<!--
<bf/Arguments/
-->
<bf/引き数/
<verb>
	struct cfs_zapfile_out {  /* CFS_ZAPFILE is a venus->kernel call */
	    ViceFid CodaFid;
	} cfs_zapfile;
</verb>

<!--
<bf/Description/ Remove all entries which have the (dir vnode, name)
pair. This is issued as a result of an invalidation of cached
attributes of a vnode.
-->
<bf/詳細/ ディレクトリの vnode と名前の組みを持つすべてのエントリを削除
します。キャッシュされた vnode の属性が失効となった結果、発行されます。

<!--
<bf/NOTE/ Call is not named correctly in NetBSD and Mach. 
The minicache <tt/zapfile/ routine takes different arguments. Linux
does not implement the invalidation of attributes correctly. 
-->
<bf/注記/ コールは NetBSD および Mach で正しい名前ではありません。ミニ
キャッシュの <tt/zapfile/ ルーチンの引き数は異なっています。Linuxは、属
性の失効を正しく実装していません。


<sect1>ZAPDIR<p>

<!--
<bf/Arguments/
-->
<bf/引き数/
<verb>
	struct cfs_zapdir_out {	  /* CFS_ZAPDIR is a venus->kernel call */
	    ViceFid CodaFid;
	} cfs_zapdir;
</verb>

<!--TYPO issed は issued-->
<!--
<bf/Description/ Remove all entries in the cache lying in a directory
<tt/CodaFid/, and all children of this directory. This call is issed
when Venus receives a callback on the directory.
-->
<bf/詳細/ ディレクトリ <tt/CodaFid/ およびこのディレクトリのすべての子の
エントリを、キャッシュの中から、すべて削除します。Venus がディレクトリの
callback を受け取った時に発行されます。

<sect1>ZAPVNODE<p>

<!--
<bf/Arguments/
-->
<bf/引き数/
<verb>
	struct cfs_zapvnode_out { /* CFS_ZAPVNODE is a venus->kernel call */
	    struct CodaCred cred;
	    ViceFid VFid;
	} cfs_zapvnode;
</verb>

<!--
<bf/Description/ Remove all entries in the cache carrying the <tt/cred/ and
<tt/VFid/ as in the arguments. This downcall is probably never
issued. 
-->
<bf/詳細/ 引き数で渡される <tt/cred/ および <tt/VFid/ を持つキャッシュの
中のエントリをすべて削除します。このコールはたぶん発行されることはありま
せん。

<sect1>PURGEFID<p>

<!--
<bf/Summary/
-->
<bf/概要/

<!--
<bf/Arguments/
-->
<bf/引き数/
<verb>
	struct cfs_purgefid_out { /* CFS_PURGEFID is a venus->kernel call */
	    ViceFid CodaFid;
	} cfs_purgefid;
</verb>

<!--
<bf/Description/ Flush the attribute for the file. If it is a dir (odd
vnode), purge its children from the namecache remove the file from the
namecache.
-->
<bf/詳細/ ファイルのための属性をフラッシュします。それがディレクトリ (や
変な vnode) なら、ネームキャッシュからのその子を除去し、ネームキャッシュ
からファイルを削除します。


<sect1>REPLACE<p>

<!--
<bf/Summary/ Replace the Fid's for a collection of names.
-->
<bf/概要/ 名前のコレクションのための Fid を置きかえます。

<!--
<bf/Arguments/
-->
<bf/引き数/
<verb>
	struct cfs_replace_out { /* cfs_replace is a venus->kernel call */
	    ViceFid NewFid;
	    ViceFid OldFid;
	} cfs_replace;
</verb>

<!--
<bf/Description/ This routine replaces a ViceFid in the name cache
with another.  It is added to allow Venus during reintegration to
replace locally allocated temp fids while disconnected with global
fids even when the reference count on those fids are not zero.
-->
<bf/詳細/ このルーチンはネームキャッシュの中の ViceFid を別のものに置き
かえます。切断されている間ローカルに割当てられたテンポラリ fid をグロー
バル fid に置きかえるための再統合の間、それらの fid の参照カウントが 0
でないときでさえ、Venus に許可を追加します。

<!--
&newpage;<sect> Initialization and cleanup <p>
-->
<sect> 初期化とクリーンアップ <p>

<!--
This section gives brief hints as to desirable features for the Coda
FS Driver at startup and upon shutdown or Venus failures.  Before
entering the discussion it is useful to repeat that the Coda FS Driver
maintains the following data:
-->
<!--draft2-->
起動時および停止時あるいは Venus の故障時に Coda FS ドライバ用に望まれる
機能を、簡潔にこのセクションで述べます。説明を始める前に、Coda FS ドライ
バが次のデータを管理していることを再確認しておきましょう。

<enum>
<!--
<item> message queues
<item> cnodes
<item> name cache entries
-->
<item> メッセージキュー
<item> cnode
<item> ネームキャッシュエントリ
</enum>
<!--
The name cache entries are entirely private to the driver, so they can
easily be manipulated.   The message queues will generally have clear
points of initialization and destruction.  The cnodes are much more
delicate.  User processes hold reference counts in Coda filesystems
and it can be difficult to clean up the cnodes.
-->
<!--draft2-->
ネームキャッシュエントリは完全にドライバが私有するので、それらは簡単に操
作できます。一般にメッセージキューには明確に初期化および後処理のルーチン
があるでしょう。cnode ははるかに扱いづらいものです。Coda ファイルシステ
ム中にユーザプロセスから参照されている回数を保持しているので、cnode をク
リーンアップするのは困難かもしれません。

<!--
It can expect requests through:
-->
<!--draft2-->
次のものから要求が来る可能性があります -
<enum>
<!--
<item> the message subsystem
<item> the VFS layer
<item> pioctl interface
-->
<item> メッセージサブシステム
<item> VFS 層
<item> pioctl インターフェース
</enum>
<!--
Currently the <em/pioctl/ passes through the VFS for Coda so we can
treat these similarly. 
-->
現在、 <em/pioctl/ は VFS を介して Coda に渡されるので、これらを同様に扱
うことができます。

<!--
<sect1> Requirements <p>
-->
<sect1> 必須条件 <p>

<!--TYPO accomodated は accommodated-->
<!--
The following requirements should be accomodated:
-->
次の必須条件に対応するべきです -
<enum>
<!--TYPO queueus は queues-->
<!--
<item> The message queueus should have <tt/open/ and <tt/close/
routines.  On Unix the opening of the character devices are such
routines.  
-->
<item> メッセージキューは <tt/open/ および <tt/close/ ルーチンを持ってい
るはずです。Unix 上のキャラクタデバイスのオープンはそういったルーチンで
す。
  <itemize> 
<!--
  <item> Before opening, no messages can be placed. 
  <item> Opening will
  remove any old messages still pending.  
  <item> Close will notify any sleeping
  processes that their upcall cannot be completed. 
  <item> Close will free all
  memory allocated by the message queues.
-->
  <item> オープンの前に、メッセージを置くことはできません。
  <item> オープンは保留のままの古いメッセージをすべて削除します。
  <item> クローズは upcall を完了できないスリープ中のプロセスすべてに通
  知を行うでしょう。
  <item> クローズはメッセージキューに割当てられたすべてのメモリを解放す
  るでしょう。
  </itemize>

<!--
<item> At open the namecache shall be initialized to empty state. 
-->
<!--draft2-->
<item> オープンでネームキャッシュは空の状態に初期化すべきです。

<!--
<item> Before the message queues are open, all VFS operations will
fail. Fortunately this can be achieved by making sure than mounting
the Coda filesystem cannot succeed before opening.
-->
<item> メッセージキューをオープンする前は、VFS 操作はすべて失敗するでしょ
う。幸運にも、オープンする前は Coda ファイルシステムのマウントが成功しな
いので、これにより確認することができます。

<!--
<item> After closing of the queues, no VFS operations can succeed.
Here one needs to be careful, since a few operations (lookup,
read/write, readdir) can proceed without upcalls.  These must be
explicitly blocked. 
-->
<item> キューのクローズの後は、VFS 操作は成功しません。ここで気を付けな
ければならないことは、少数の操作 (lookup, read/write, readdir) は upcall
なしで成功してしまうことです。これらは明示的に阻止しなければなりません。

<!--
<item> Upon closing the namecache shall be flushed and disabled.
-->
<item> クローズに際してネームキャッシュはフラッシュされ無効になるものと
します。

<!--
<item> All memory held by cnodes can be freed without relying on
upcalls. 
-->
<item> cnode に保持されたすべてのメモリは upcall に依存せずにすべてを解
放することができます。

<!--TYPO upcalss は upcalls-->
<!--
<item> Unmounting the file system can be done without relying on
upcalss. 
-->
<item> ファイルシステムのアンマウントは upcall に依存せずに行うことがで
きます。

<!--
<item> Mounting the Coda filesystem should fail gracefully if Venus
cannot get the <tt/rootfid/ or the attributes of the <tt/rootfid/.
The latter is best implemented by Venus fetching these objects before
attempting to mount. 
-->
<item> Venus が <tt/rootfid/ もしくは <tt/rootfid/ の属性を得られない場
合、コーダファイルシステムのマウントは優雅に失敗するべきです。マウントを
試みる前に、これらのオブジェクトを先読みするために、Venus が lattr を実
行すると良いでしょう。

</enum>

<!--
<bf/NOTE/  NetBSD in particular but also Linux have not implemented
the above requirements fully.  For smooth operation this needs to be
corrected. 
-->
<bf/注記/  特に NetBSD で、さらに Linux も上記の必須条件を完全に実装して
はいません。円滑な操作のために、これを改善していく必要があります。

<!--
&newpage;<sect> Inode numbers <p>
-->
<sect> Inode 番号 <p>

<!--
The Unix stat system call returns inode numbers for files.  These
should be correct for Coda files for library calls like getwd and tar
to function correctly.
-->
Unix の stat システムコールはファイル用の inode を返します。getwd や tar
のようなライブラリコールが正しく機能するように、Coda ファイル用に改善す
る必要があります。

<!--
The mount points of volumes complicate the values which Venus assigns to the inode numbers in the statbuf structure.  The rules are as follows:
-->
ボリュームのマウントポイントは、Venus が statbuf 構造体の中に割当てる
inode 番号の値を複雑にします。規則は次のとおりです -

<enum>
<!--
<item> A fid is converted to an integer (vol<<20) + (vnode<<10) + (uniq).
<item> If a fid is the root of a volume, then it is assigned the inode number of the symlink which is its mountpoint. 
-->
<item> fid は整数 (vol<<20) + (vnode<<10) + (uniq) に変換されます。
<item> fid がボリュームのルートである場合、そのマウントポイントであるシ
ンボリックリンクの inode 番号が割当てられます。
</enum>

<!--
The kernel should never cache the symlink mountpoints but may see them
in case they cannot be covered. Also downcalls are made to purge the
symlink fid from the cache, despite the fact that the kernel has never
seen the mountpoint fid before.
-->
<!--draft2-->
カーネルはマウントポイントのシンボリックリンクをキャッシュしてはなりませ
んが、それらをカバーすることができない場合見ることはかまいません。さらに
キャッシュからシンボリックリンク fid を除去する downcall が、カーネルが
マウントポイントの fid を以前に見ていないという事実にかかわらず、行われ
ます。

<!--
Kernel code for Coda will need to implement a lookup mechanism to find
vnodes (BSD) inodes (Linux) or FileHandles (Win) based on Fid, and it
will need to be careful to get things right for volume roots.
-->
Coda 用のカーネルコードは Fid に基づき vnode (BSD), inode (Linux),
FileHandle (Win) を探す lookup の仕組みを実装するために必要で、ボリュー
ムのルートを正しく得るよう気をつける必要があるでしょう。

<sect> 日本語訳について
<p>
日本語訳は Linux Japanese FAQ Project が行いました。
翻訳に関するご意見は JF プロジェクト &lt;JF@linux.or.jp&gt; 宛に連絡
してください。

<descrip>
<tag>v1.2</tag>
翻訳:
野本浩一 &lt;hng@ps.ksky.ne.jp&gt;

<verb>
校正: 
中谷 千絵さん <jeanne@mbox.kyoto-inet.or.jp>、
Seiji Kanekoさん <skaneko@a2.mbn.or.jp>
</verb>
</descrip>

</article>
