「LIBRARY PUBLIC DOCUMENT NDOS」の版間の差分

2017年8月18日 (金) 01:00時点における最新版

NDOS 1.0 - By Konami Man, 2-2001

これは何？

NDOSはC関数ライブラリで、MSX-DOS2の機能(キーボードインプット/アウトプット、スクリーン、ファイル/ディレクトリアクセス、環境変数の取り扱い、セクターへの直接アクセス、ディスクエラーハンドリングルーチンへの定義などなど)の全てが簡単に使えます。 NSOD関数はオペレーティングシステムへの呼び出しをするためにNASMライブラリの関数を呼び出します。そのためNDOSの関数を使うプログラムをコンパイルする際は、常に両方のライブラリをリンクする必要があります。

NDOS全体の配布物は以下のものを含んでいます。

LIBNDOS.LIB: NDOSの全ての関数のオブジェクトコードを含むライブラリファイル。

NDOS.H: 全ての関数のヘッダファイル。ある関数のために定義するデータ構造や定数も含まれます。

DOSCODES.H: "MSX-DOS2ファンクションコード仕様"のドキュメントにあるそのままの、DOS2関数の全ての名前を定義しています。"MSX-DOS2プログラムインターフェース仕様"にあるのと同じ、起き得るエラー名前も定義していますが、コンパイラがピリオドを受け付けないので"."に対しては"_"を使用しています。そのため、いくつかのエラーは実際のものとは違う名前で定義されています。これはまた、いくつかの関数でも同時に起こります。変更された名前を持つものは以下の通りです。

_SEEKE 元の名前は .SEEK (error 0F3h)
_FOPENE 元の名前は .FOPEN (error 0CAh)

このファイルはNASMの配布物に含まれるものと同一です。

NDOS.TXT: このドキュメントです。

NDOSE.TXT: このドキュメントの英語版です。

Files * .C and * .AS: 全てのNDOS関数のソースです。

このマニュアルはファイルデスクリプタ（ファイルハンドル）、FIB、環境変数といったシステムの概念を知っていることを前提としています。これらの概念はDOSマニュアル、"MSX-DOS2プログラムインターフェース仕様"、"MSX-DOS2ファンクションコード仕様"などで説明されています。

同様に、NDOS関数の詳細が、関係するDOSコールについても説明しているわけではありません。例えばそれぞれが生成するエラーコード、もしくは実際にデバイスを参照するファイルデスクリプタなどです。この種の情報はドキュメントも参照する必要があります。

NDOS関数はDOS2で使用するために設計されています。DOS1で動くものがあるかもしれませんが、保証はありません。

構造

NDOS.Hにはいくつかの関数に必要なデータ構造体が定義されています。それらは以下の通りです。

FLAGS

typedef struct {
        b0: 1;
        b1: 1;
        b2: 1;
        b3: 1;
        b4: 1;
        b5: 1;
        b6: 1;
        b7: 1;
} flags;

入力や出力パラメータにフラグ型が必要な関数に使われる型で、1バイトにエンコードされた複数のビットの集合です。int型とフラグは単純なキャストによって相互変換が可能です。

DISKPARAM

typedef struct {
        uchar phdrive;
        uint  secsize;
        uchar secpclus;
        uint  secrsv;
        uchar fatcopies;
        uint  rootentr;
        uint  sectotal;
        uchar mediaid;
        uchar secpfat;
        uint  firstroot;
        uint  firstdata;
        uint  maxclus;
        uchar dirty;
        ulong volid;
        uint  clustotal;
        uint  clusfree;
        uint  dpbpnt;
        char  unused[2];
} diskparam;

この構造体はディスクのパラメータを取得するために、GETDPAR関数によって使用されます。それぞれのフィールドの意味は以下の通りです。

phdrive: 物理的なユニット数(1 = A :, etc)
secsize: セクターサイズ(普通は常に512)
secpclus: 1クラスターあたりのセクター数
secrsv: リザーブされたセクター
fatcopies: FATのコピーされた数
rootentr: rootディレクトリのエントリ数
sectotal: 論理セクターの総数
mediaid: デバイスデスクリプタバイト
secpfat: FAT当たりのセクタ数
firstroot: rootディレクトリの最初のセクタ
firstdata: データエリアの最初のセクタ
maxclus: クラスター番号の最大値
dirty: ゼロでない場合は、UNDELで復活可能な削除済みファイルがあることを示す
volid: ボリュームラベル（-1の場合は無し）
clustotal: クラスターの総数
clusfree: フリークラスターの数
dpbpnt: ファイルのDPB (Drive Parameters Block)へのポインタ
unused: 予約済みで使用禁止

FIB

この構造体はFIB（File Info Block）型のメモリブロックを表し、普通はファイルの検索（FFIND関数）につかわれますが、ファイル名やFIBをわずかにサポートする、他の関数などでも使われます。

typedef struct {
        char  alwaysff;
        char  fname[13];
        char  attrib;
        uint  time;
        uint  date;
        uint  startclus;
        ulong fsize;
        uchar drive;
        char  internal[38];
} fib;

それぞれのフィールドの意味は次の通りです。

alwaysff: 常に0xFFを値に持ちます。これはFIBであり、ファイル名ではないことを意味します。
fname: 読み込み可能なファイルフォーマットのファイル名です(file.ext)
attrib: ファイルアトリビュートを表すバイトです。
time: ファイルの最終変更時間です。
date: ファイルの最終変更時です。
startclus: ファイルのイニシャルクラスタです。
fsize: ファイルサイズです。
drive: 論理ユニットです(1 = Aなど)
internal: 内部システムインフォメーションです。変更してはいけません。

DATE と TIME

それぞれ日付と時間を表す構造体で、システムやファイルの日付を取得/設定する関数で使用されます。

typedef struct {
        int year;
        int month;
        int day;
        int wday;
} date;

typedef struct {
int hour;
        int minute;
        int second;
} time;

year: 年 (1980 から 2079)
month: Mes (1= 1月から 12= 12月)
day: 日 (1 から 31)
wday: 曜日 (0=日曜から 6=土曜)
hour: 時間 (0 から 23)
minute: 分 (0 から 59)
second: 秒 (0 から 59)

FFINDのようないくつかの関数は、int値でエンコードされた日時を必要としたり返したりします。intから日時の構造体に、もしくはその逆に変換する場合、はITOT、TTOI、ITOD 、DTOIなどの関数が使えます。

PARSEDATA

PARSEPとPARSEF関数で、それぞれrouteやファイル名を変換するために使われる構造体です。

それぞれのフィールドは以下を意味します。

termchar

チェーンの終わりへのポインタです。

lastitem

文字列の最後の要素へのポインタです。

logdrive

論理ユニットです(1 = A, etc.)

f

各種フラグ:

f.b0=1 ユニット以外が指定されている

f.b1=1 ディレクトリが指定されている

f.b2=1 ユニットが指定されている

f.b3=1 ファイル名が指定されている

f.b4=1 拡張子が指定されている

f.b5=1 最後の要素があいまい（ワイルドカードを使用）

f.b6=1 最後の部分が"."もしくは".."

f.b7=1 最後の部分が".."

定数

NDOS.Hはいくつかの定数を定義しています。これは関数のパラメータや結果の翻訳に使用することができます。これらは以下の通りです。

システムファイルデスクリプタ

ファイルデスクリプタ（ファイルハンドル）をパラメータとしてサポートするすべての関数においては、ファイルの代わりにデバイスへの参照ができる、システムデスクリプタを指定可能です。

STDIN (0): スクリーンアウトプット
STDOUT (1): キーパッドインプット
STDERR (2): エラーメッセージのアウトプット。普通はSTDOUTと同一です。
AUX (3): 外部デバイス。デフォルトでは何も起きません。
PRN (4): プリンタ

ファイルオープンのモード

これらはファイルのオープンと作成のファンクションです。

F_NOWRITE: ファイルに書き込めません。
F_NOREAD: ファイルから読み込めません。
F_NOINH: このファイルはFORKによって作成された子プロセスによって継承されません。

"|"オペレータを使用して、二つかそれ以上を組み合わせることができます。例えば F_NOINH | F_NOWRITEは、オープニングモード、ファイルは読み込み専用で継承されないことを意味します。

ファイルの属性

これらはファイルの作成と参照属性の関数で使用されます。

A_RDO: リードオンリー
A_HID: 隠し
A_SYS: システム
A_VOL: ファイルではなくボリュームラベル
A_DIR: ディレクトリ
A_ARC: アーカイブ
A_DEV: ファイルでなくデバイス
A_NEW: ファイルを作成する関数で使用され、もし、それが一つですでに同じ名前を持つファイルが存在した場合、消されることなく、エラーが生成される。

"|"オペレータを使用して、二つかそれ以上を組み合わせることができます。例えば A_HID | A_DIRをFFINDの検索アトリビュートとして指定した場合、隠しファイルとサブディレクトリを普通のファイルに加えて検索します。

Methods of obtaining a character

文字を取得する方法

NGETC関数を使ってキーボードから文字を取得する際に、これらが使用できます。

NOWAIT: キーを特定しない場合、ユーザーからの入力まで待ちます。

特定せず、またユーザーからなんのキーの入力もない場合、この関数はすぐに0を返します。

NOTICE: 指定された場合、押されたキーに対応する文字はスクリーンに表示されません。

They can be combined with the "|" operator. これらは"|"で連結可能です。

NDOS.Hで定義されているその他の定数

Uchar	unsigned charと同じ
Uint	unsigned intと同じ
Ulong	unsigned longと同じ
Fhanle	intと同じ
ESC	27 (escape code)と同じ

これは定数ではなく、文字列"\n\r"へのポインタです。CR_LFはNEWLINEやFNEWLINEマクロにおいて、文字列"\n\r"の代わりに使われます。これはコンパイル時コンパイラに対して、この文字列をそれぞれ定義させずにこれらのマクロをコールさせます。

関数の記述フォーマット

全てのNDOSの詳細な記述です。記述は次のフォーマットを持っています。

[(N)] NAME [*]

Exit name (entry, ..., entry)

Description of function.

DOS functions used [*]


-----
(...)
サブ関数のサンプル（とてもシンプルな関数を除く）、もしくは他の関数への参照
(...)
-----

あるNDOS関数はほかのC言語の標準ライブラリ（OPEN,GETC,PRINTFなど）のNDOS関数と同じ名前を持っていますが、使い方がかなり違います。この衝突をさけるため、これらの関数は"N"を最初の文字にもつNOPEN, NGETC, NPRINTFなどになります。このタイプの関数の記述においては、"N"が名前の前につきます。

しかしながら、 NDOSに属する意味の"N"を持たない関数名を、コンパイラに対して強制することも可能です。ディレクティブ"#define NSTDIO" (これは"#include NDOS.H"の前に置かなければいけません)もしくはコンパイラコマンドラインに -DNSTDIOを含むどちらでも、これはNSTDIOシェルの定義は成功します。？？Nで始まる名前と、初めにNのつかない名前の両方をマクロとする定義（例えば"#define open nopen"）に影響があります。

ある関数は関連するオブジェクトコードを持たず、シンプルにNDOS.Hの中でマクロが定義されているだけで、他の関数を代わりに読んでいます。例えば、PUTC関数はスクリーンに文字を書き出しますが、これは実際のところ、FPUTC（文字をファイルに書き込む）にファイルデスクリプタとしてSTDOUTを指定して呼び出すマクロです。これらの記述には、関数名の後にアスタリスクが付きます。

それぞれの関数の記述の後にDOSコールがリストで挙げられます。これらのコールの次に付けられるアスタリスクは、それがディスクエラーハンドリングルーチンから安全に使えることを示します（NDOSのATERROR関数と一緒に64hのDOSコールが定義されています）。なので、もし、関数から呼び出される全てのコールにアスタリスクがついている場合、その関数自体がディスクエラーハンドリングルーチンから安全に使用できるということです。

関数はアルファベット順になっており、Nがつく関数はそれがつくかどうか考慮されていません。以下はクリックリファレンスとして全ての関数が挙げられており、この後のセクションがそれぞれの詳細な記述となっています。

ABSEC: Read or write disk sectorsディスクセクターの読み込み、書き込みをします。
ASSIGN: Assigns logical drives to physical drives物理ドライブに論理ドライブをアサインします。
(N) ATERROR: Defines a function to call in case of disk errorディスクエラーの際にコールする関数を定義します。
(N) ATEXIT: Defines a function to call when the program is finishedプログラムが終了した際にコールする関数を定義します。
BEEP *: It sounds a "beep"ビープ音を鳴らします。
BS *: Deletes the character to the left of the cursorカーソルの左側の文字を削除します。
BTOA *: Converts a number to a string on binary basisバイナリベースで数値を文字に変換します。
BUFFERS: Sets or queries the number of system sector buffersシステムセクターバッファの番号を設定、問い合わせします。
(N) CHDIR: Change the current directoryカレントディレクトリを変更します。
CHKCHAR: Helps manipulate strings containing graphic charactersグラフィックキャラクタを含む文字列の取り扱いを補助します。
(N) CLERR *: Overrides the error condition caused by a previous function以前の関数で起こされたエラー状態を上書きします。
(N) CLOSE: Closes an open fileオープンしたファイルをクローズします。
CLS *: Clears the screenスクリーンをクリアします
CREATE: Create a fileファイルを作成します。
CURBLK *: Select the normal cursorノーマルカーソルを選択します。
CURDOWN *: Moves the cursor one position downカーソルを一段階下に移動します。
CURLEFT *: Moves the cursor one position to the leftカーソルを一段階左に移動します。
CUROFF *: Sets the cursor to "hidden"カーソルを"hidden"に設定し、隠します。
CURON *: Sets the cursor to "visible"カーソルを"visible"に設定し、表示します。
CURRIGHT *: Moves the cursor one position to the rightカーソルを一段階右に移動します。
CURUND *: Select the small cursorスモールカーソルを選択します
CURUP *: Moves the cursor up one positionカーソルを一段階上に移動します。
DELLINE *: Deletes the line in which the cursor isカーソルがある位置の行を削除します。
DELTOENDL *: Delete from the cursor to the end of the lineカーソルから行末までを削除します。
DELTOENDS *: Delete from the cursor to the end of the screenカーソルからスクリーンの最後までを削除します。
DOSVER: Returns the version of MSX-DOSのバージョンを返します。
DTOI: Encode a structure of type "date" into an integer"data"型の構造体をintにエンコードします。
DUPFH: Duplicate a file descriptorファイルデスクリプターを複製します。
EOF: Indicates whether the pointer of an open file is beyond the endオープンしたファイルのポインタが終了位置を超えていないか示します。
ENSUREFH: Moving Internal System Buffers to Disk Dataファイル内に書かれている内部システムバッファをディスクデータに移動します。
That have been written in a file
(N) EXIT: Program execution endsプログラム実行を終了します。
EXPLAIN: Gets an error message for a given error code与えられたエラーコードのエラーメッセージを取得します。
FDELETE: Delete a fileファイルを削除します。
FILEDT: Queries / sets date / time of an open / unopened fileオープン済み/未オープンのファイルの時間を問い合わせ/セットします。
FFIND: Search for files on diskディスクのファイルを検索します。
(N) FGETC: オープンしたファイルから文字を読み出します。
FILEATT: オープンした、もしくはしていないファイルのアトリビュートを取得、変更します。
FINDENV: 環境変数の名前と値を取得します。
FLUSH: 使用できないディスクバッファを消去します。
FNEWLINE *: ファイルにラインブレイクを書き出します
FORK: 子プロセスを実行する環境を準備します
FORWARD *: ファイルの終了部分にポインタを置きます
FPRINT: ファイルに文字列を書き出します
(N) FPRINTF: ファイルに整形した文字列を書き出します
(N) FPUTC: オープンしたファイルに文字を書き出します
(N) FTELL *: オープンしたファイルの現在のポインタ位置を返します
GDATE: システムデートを取得します
GETARG: コマンドラインパラメータを取得します
(N) GETC: キーボードキャラクタを取得します。
(N) GETCWD: カレントディレクトリを返します。
GETDPAR: ディスクのパラメータを取得します。
GETDRV: デフォルトドライブを返します。
GETDTA: ディスクの転送の実際のアドレスを取得します？。DOSファンクション1用？？
(N) GETENV: 環境変数を取得します
GETERR: 最後に発生したDOSエラーのコードを返します
GETFATT *: オープンしていないファイルのアトリビュートを取得します
GETFDATE *: オープンしていないファイルの日付を取得します
GETFTIME *: オープンしていないファイルの時間を取得します
GETHATT *: オープンしているファイルのアトリビュートを取得します
GETHDATE *: オープンしているファイルの日付を取得します
GETHTIME *: オープンしているファイルの時間を取得します
GETLOGV: 存在するディスクドライブを示します
GTIME: システム時間を取得します
HOME * カーソルをスクリーンのトップに移動します
INPUT: キーボードから文字列を取得します
INSLINE *: カーソルの上に新しい行を追加します。
IOCTRL: ファイルデスクリプタのコントロールをします？？
ITOA *: 10進数ベースで数値を文字列に変換します。
ITOD: エンコードされたdate構造体をintにデコードします
ITOT: エンコードされたdate構造体をintにデコードします
JOIN: コントロールのレジュームを親プロセスに示します
LOCATE *: カーソル位置を与えられた座標に置きます
(N) MKDIR: ディレクトリを作成します。
MOVE: ファイルを移動します。
MPRINT: スクリーンに複数の文字列を書き出します
MPUTC: 複数のオンスクリーン文字を書き出します
NEWLINE *: スクリーンにラインブレイクを書き出します。
NTOA: 何進数でも数値を文字列に変換します。
NUMARGS: コマンドラインでパラメータの数を取得します
(N) OPEN: ファイルをオープンします。
PARSEF: ファイル名情報を検証し、返します
PARSEP: ファイルパス情報を検証し、返します。
PAUSEKEY *: ユーザーがキーを押すのを待ちます（WAITKEYも参照してください）
PRINT *: オンスクリーン文字列を書き出します。
(N) PRINTF: スクリーンで整形された書き出しです。
PRINTLN *: スクリーンラインにラインブレイクを書き出します？？？
(N) PUTC *: スクリーンに文字を書き出します。
RAMDISK: RAMディスクを作成したり、破壊したり、サイズをチェックします。
RDSEC *: ディスクセクターを読み出します。
(N) READ: ファイルからデータを読み出します。
REDIR: リダイレクションの状態をチェックしたり、変更したりします。
(N) RENAME: ファイルをリネームします。
(N) REWIND *: オープンしたファイルのポインタをファイルの先頭に置きます。
(N) RMDIR: ディレクトリを削除します。
SDATE: システムの日付を設定します。
SEEK: オープンしたファイルのポインタを変更します。
SETDRV: デフォルトドライブを選択します。
SETDTA: DOSファンクション1のためのディスク転送エリアを設定します。
(N) SETENV: 環境変数の値を設定します。
SETFATT *: オープンしていないファイルの属性を設定します。
SETFDATE *: オープンしていないファイルの日付を設定します。
SETFTIME *: オープンしていないファイルの時刻を設定します。
SETHATT *: オープンしたファイルの属性を設定します。
SETHDATE *: オープンしたファイルの日付を設定します。
SETHTIME *: オープンしたファイルの時間を設定します。
(N) SPRINTF: 整形された出力を記憶します。
STIME: システム時間を設定します。
SUPRLINE *: カーソルのある行を削除します。
TESTFH: 与えられたファイルにファイルデスクリプタが対応しているかチェックします。
TTOI: "time"型の構造体をint型にエンコードします。
VERIFY: ファイルアクセスの際にブートセクターの自動確認を有効化、無効化、確認を行います。
WAITKEY: ユーザーからキーの入力があるまで待ちます(PAUSEKEYも参照してください)
WPATH: FFINDで最後に発見されたファイルのフルパスを返します。
(N) WRITE: ファイルに日付を書き出します
WRSEC: ディスクセクターを書き出します。
XTOA *: 16進数ベースで数値を文字列に変換します

関数の記述

[WIKI編集：翻訳準備中です]

いつもの

NDOSはフリーウェアです。そのため、自分のすきなようにこれを配布してください。ただし、完全なパッケージ（セクション１のリスト参照）でのみ配布して、改変した場合は、それを別パッケージで説明してください。

もし、私にハッパをかけたり励ましたり...などなどしたい場合は、[スパム対策のため連絡先省略]にコンタクトするか、私のホームページ、http://www.konamiman.comに来てください。

Y que Kyoko es la es la mas mejor.