.\" cdb.1: cdb command tool manpage
.\"
.\" This file is a part of tinycdb package.
.\" Copyright (C) 2001-2023 Michael Tokarev <mjt+cdb@corpit.ru>
.\" Tinycdb is licensed under MIT license.
.\"
.TH cdb 1 "Jan 2009"
.SH "نام (NAME)"
cdb \- ابزار ایجاد و خواندن پایگاه داده‌های ثابت Constant Database
.SH "خلاصه دستور (SYNOPSIS)"
\fBcdb\fR \-q [\-m] [\-n \fInum\fR] \fIdbname\fR \fIkey\fR
.br
\fBcdb\fR \-d [\-m] [\fIdbname\fR|\-]
.br
\fBcdb\fR \-l [\-m] [\fIdbname\fR|\-]
.br
\fBcdb\fR \-s [\fIdbname\fR|\-]
.br
\fBcdb\fR \-c [\-m] [\-t \fItmpname\fR|\-] [\-p \fIperms\fR] [\-weru0] \fIdbname\fR [\fIinfile\fR...]

.SH "توضیحات (DESCRIPTION)"
ابزار
\fBcdb\fR
برای پرس‌وجو، استخراج داده‌ها (دامپ)، فهرست کردن، تجزیه‌وتحلیل یا ساخت فایل‌های CDB (پایگاه‌داده ثابت یا Constant DataBase) به کار می‌رود. ساختار cdb در صفحه راهنمای
\fIcdb\fR(5)
توضیح داده شده است. این صفحه راهنما منطبق بر نسخه
\fB0.81\fR
از بسته
\fBtinycdb\fR
است.

.SS "پرس‌وجو (Query)"
دستور
\fBcdb \-q\fR
کلید داده‌شده
\fIkey\fR
را در فایل cdb مشخص‌شده
\fIdbname\fR
می‌یابد و مقدار مرتبط با آن را در صورت یافتن در خروجی استاندارد می‌نویسد (و با کد صفر خارج می‌شود)، یا در صورت پیدا نشدن با کد غیرصفر پایان می‌یابد.
\fIdbname\fR
باید فایلی با قابلیت پرش (seekable) باشد و ورودی استاندارد (stdin) نمی‌تواند به عنوان ورودی استفاده شود.
به طور پیش‌فرض،
\fBcdb\fR
تمام رکوردهای یافت‌شده را چاپ خواهد کرد.
گزینه‌های شناخته‌شده در حالت پرس‌وجو:

.IP \fB\-n\fInum\fR
باعث می‌شود
\fBcdb\fR
رکورد دارای شماره
\fInum\fR
را (با شروع از ۱) یافته و بنویسد \(em هنگامی که چندین رکورد با یک کلید مشخص وجود دارد.

.IP \fB\-m\fR
پس از هر مقدار چاپ‌شده یک خط جدید اضافه می‌شود. به طور پیش‌فرض، مقادیر چندگانه بدون هیچ نویسه جداکننده‌ای نوشته می‌شوند.

.SS "تخلیه/فهرست کردن (Dump/List)"
دستور
\fBcdb \-d\fR
محتویات را تخلیه (dump) می‌کند، و دستور
\fBcdb \-l\fR
کلیدهای
\fIcdbfile\fR
(یا ورودی استاندارد در صورت عدم تعیین) را بر اساس قالب کنترل‌شده با گزینه
\fB\-m\fR
در خروجی استاندارد فهرست می‌کند.
زیربخش «قالب ورودی/خروجی» در ادامه را ببینید. خروجی
\fBcdb \-d\fR
می‌تواند به عنوان ورودی برای
\fBcdb \-c\fR
استفاده شود.

.SS "ساخت (Create)"
پایگاه‌داده Cdb در دو مرحله ساخته می‌شود: ابتدا یک پایگاه‌داده موقت ایجاد می‌شود و پس از تکمیل، به طور اتمیک به مکان دائمی تغییر نام می‌یابد. این کار نیاز به قفل‌گذاری میان خوانندگان و نویسندگان (یا سازندگان) را از بین می‌برد.
\fBcdb \-c\fR
تلاش می‌کند تا cdb را در فایل
\fItmpname\fR
(یا در صورت عدم تعیین گزینه
\-t
در
\fIdbname\fR
همراه با پسوند ".tmp") بسازد و سپس نام آن را به
\fIdbname\fR
تغییر دهد. این دستور فایل‌های ورودی
\fIinfile\fR
مشخص‌شده (یا ورودی استاندارد در صورت عدم تعیین) را خواهد خواند.
گزینه‌های شناخته‌شده در حالت ساخت:

.IP "\fB\-t \fItmpname\fR"
استفاده از
\fItmpname\fR
داده‌شده به عنوان فایل موقت. به طور پیش‌فرض برابر است با
\fIdbname\fR.tmp
(یعنی فایل خروجی به همراه پسوند .tmp).
توجه داشته باشید که
\fItmpname\fR
باید در همان فایل‌سیستم فایل خروجی قرار داشته باشد، زیرا
.B cdb
از فراخوانی سیستمی
.IR rename (2)
برای نهایی‌سازی ساخت پایگاه‌داده استفاده می‌کند.
اگر
\fItmpname\fR
یک خط تیره منفرد (\-) باشد، هیچ فایل موقتی ایجاد نمی‌شود و پایگاه‌داده مستقیماً درجا ساخته می‌شود. این حالت زمانی کاربرد دارد که تغییر نام نهایی توسط فراخواننده انجام شود.

.IP "\fB\-p \fIperms\fR"
مجوزهای دسترسی برای فایل تازه ایجادشده (معمولاً یک عدد در مبنای هشت، مانند 0644).
به طور پیش‌فرض مجوزها 0666 هستند (با اعمال umask فرآیند جاری).
اگر این گزینه مشخص شود، مقدار umask جاری بی‌اثر خواهد بود.

.IP \fB\-w\fR
هشدار در مورد کلیدهای تکراری.

.IP \fB\-e\fR
توقف در صورت برخورد با کلیدهای تکراری (شامل \-w نیز می‌شود).

.IP \fB\-r\fR
جایگزینی کلید موجود با کلید جدید در صورت وجود تکرار.
این کار ممکن است نیازمند بازنویسی فایل پایگاه‌داده برای حذف رکوردهای قدیمی باشد و روندی کند داشته باشد.

.IP \fB\-0\fR
پر کردن رکوردهای موجود با صفر (zero-fill) هنگام اضافه شدن رکوردهای تکراری.
این روش از
\fB\-r\fR
سریع‌تر است، اما در صورت وجود تکراری‌ها صفرهای اضافی در فایل پایگاه‌داده باقی می‌گذارد.

.IP \fB\-u\fR
عدم اضافه کردن رکوردهای تکراری.

.IP \fB\-m\fR
تفسیر ورودی به عنوان دنباله‌ای از خطوط (یک رکورد در هر خط) که در آن مقدار به وسیله نویسه‌های فاصله یا تب از کلید جدا شده است، به جای قالب بومی cdb (بخش «قالب ورودی/خروجی» در ادامه را ببینید).

.PP
توجه داشته باشید که استفاده از هر گزینه‌ای که نیازمند بررسی کلیدهای تکراری باشد، روند ساخت را
\fIبه‌طور چشمگیری\fR
کند می‌کند، به‌ویژه برای پایگاه‌های داده بزرگ.

.SS "آمار (Statistics)"
دستور
\fBcdb \-s\fR
فایل
\fIdbfile\fR
را تجزیه‌وتحلیل کرده و خلاصه‌ای از آن را در خروجی استاندارد چاپ می‌کند. این آمار شامل موارد زیر است: تعداد کل ردیف‌ها در یک فایل، حداقل، میانگین و حداکثر طول کلیدها و مقادیر، جداول هش (حداکثر ۲۵۶) و ورودی‌های استفاده‌شده، تعداد تصادم‌های هش (یعنی بیش از یک کلید به یک ورودی جدول هش اشاره کنند)، حداقل، میانگین و حداکثر اندازه جدول هش (از جداول غیرخالی)، و تعداد کلیدهایی که در ۱۰ فاصله مختلف از شاخص محاسبه‌شده جدول هش خود قرار دارند \(em کلیدهای در فاصله ۰ تنها به یک جستجو در جدول هش نیاز دارند، فاصله ۱ \(em دو جستجو و به همین ترتیب؛ وجود کلیدهای بیشتر در فواصل بزرگ‌تر به معنای کندتر شدن جستجو در پایگاه‌داده است.

.SS "قالب ورودی/خروجی (Input/Output Format)"
به طور پیش‌فرض،
\fBcdb\fR
داده‌ها را در قالب بومی cdb انتظار دارد (برای عملیات ساخت) یا می‌نویسد (برای تخلیه/فهرست کردن). قالب بومی cdb دنباله‌ای از رکوردها به فرم زیر است:
.PP
.nf
+\fIklen\fR,\fIvlen\fR:\fIkey\fR\->\fIval\fR\en
.fi
.PP
که در آن "+"، "،"، ":"، "\-"، ">" و "\en" (خط جدید) نویسه‌های صریح هستند،
\fIklen\fR
و
\fIvlen\fR
طول کلید و مقدار به صورت اعداد ده‌دهی هستند، و
\fIkey\fR
و
\fIval\fR
خود کلید و مقدار می‌باشند. مجموعه رکوردها با یک خط خالی پایان می‌یابد. این تنها قالبی است که کلید و مقدار در آن می‌توانند حاوی هر نویسه‌ای از جمله خط جدید، صفر بیتی (\e0) و غیره باشند.

هنگامی که گزینه
\fB\-l\fR
درخواست شود (حالت فهرست کردن کلیدها)،
\fBcdb\fR
خروجی کمی تغییریافته به شکل زیر تولید می‌کند:
.PP
.nf
+\fIklen\fR:\fIkey\fR\en
.fi
.PP
(توجه داشته باشید که
\fIvlen\fR
و
\fIval\fR
به همراه جداکننده‌های اطراف حذف شده‌اند).

اگر گزینه
\fB\-m\fR
داده شود،
\fBcdb\fR
برای هر رکورد یک خط را انتظار دارد یا تولید می‌کند (خط جدید جداکننده رکورد است)، و هر خط باید شامل فاصله خالی اختیاری، کلید، فاصله خالی و مقدار تا انتهای خط باشد.
خطوطی که با نویسه هش (#) آغاز می‌شوند و خطوط خالی نادیده گرفته می‌شوند.
این همان قالبی است که ابزار
\fBmkmap\fR(1)
انتظار دارد.

.SH "خلاصه گزینه‌ها (OPTIONS SUMMARY)"
در ادامه خلاصه کوتاهی از تمام گزینه‌های پذیرفته‌شده توسط ابزار
\fBcdb\fR
آمده است:

.IP \fB\-0\fR
پر کردن رکوردهای تکراری با صفر در حالت ساخت (\fB\-c\fR).
.IP \fB\-c\fR
حالت ساخت (create).
.IP \fB\-d\fR
حالت تخلیه داده‌ها (dump).
.IP \fB\-e\fR
توقف (خطا) در صورت برخورد با کلید تکراری در حالت ساخت (\fB\-c\fR).
.IP \fB\-h\fR
چاپ راهنمای کوتاه و خروج.
.IP \fB\-l\fR
حالت فهرست کردن (list).
.IP \fB\-m\fR
ورودی یا خروجی در قالب "map" است، نه در قالب بومی cdb. در حالت پرس‌وجو، پس از هر مقدار نوشته‌شده یک خط جدید اضافه می‌شود.
.IP \fB\-n\fInum\fR
یافتن و چاپ \fInum\fRمین رکورد در حالت پرس‌وجو (\fB\-q\fR).
.IP \fB\-q\fR
حالت پرس‌وجو (query).
.IP \fB\-r\fR
جایگزینی کلیدهای تکراری در حالت ساخت (\fB\-c\fR).
.IP \fB\-s\fR
حالت آمار (statistics).
.IP "\fB\-t\fR \fItempfile\fR"
مشخص کردن فایل موقت هنگام ساخت (\fB\-c\fR) فایل cdb (استفاده از یک خط تیره منفرد (\-) به عنوان \fItempfile\fR برای عدم استفاده از فایل موقت).
.IP \fB\-u\fR
عدم درج کلیدهای تکراری (یکتا یا unique) در حالت ساخت (\fB\-c\fR).
.IP \fB\-w\fR
هشدار درباره کلیدهای تکراری در حالت ساخت (\fB\-c\fR).

.SH "نویسندگان (AUTHORS)"
بسته
\fBtinycdb\fR
توسط Michael Tokarev <mjt+cdb@corpit.ru> نوشته شده است، بر اساس ایده‌ها و قالب فایل مشترک با کتابخانه اصلی cdb اثر Dan Bernstein.

.SH "همچنین ببینید (SEE ALSO)"
cdb(5), cdb(3).

.SH "مجوز (LICENCE)"
بسته Tinycdb تحت مجوز MIT منتشر شده است.