.PU
.TH CSCOPE "1" "January 2007" "The Santa Cruz Operation" "دستورات کاربر"
.SH "نام (NAME)"
cscope \- بررسی تعاملی برنامه‌های C
.SH "خلاصه دستور (SYNOPSIS)"
.B cscope
.B [\-bCcdehkLlqRTUuVvX]
.BI [\-F symfile ]
.BI [\-f reffile ]
.BI [\-I incdir ]
.BI [\-i namefile ]
.BI [\-0123456789 pattern ]
.BI [\-p n ]
.BI [\-s dir ]
.BI [ files ]
.SH "توضیحات (DESCRIPTION)"
ابزار
.I cscope
یک ابزار تعاملی و مبتنی بر صفحه ترمینال است که به کاربر امکان می‌دهد کدهای منبع C را برای یافتن بخش‌ها و عناصر مشخص پیمایش کند.
.PP
به طور پیش‌فرض،
.I cscope
فایل‌های منبع C (.c و .h)، لکس (.l) و یاک (.y) را در دایرکتوری جاری بررسی می‌کند.
همچنین می‌توان
.I cscope
را برای فایل‌های منبع مشخص‌شده در خط فرمان فراخوانی کرد. در هر دو حالت،
.I cscope
دایرکتوری‌های استاندارد را برای فایل‌های #include که در دایرکتوری جاری پیدا نمی‌شوند جستجو می‌کند.
.I cscope
از یک جدول ارجاع متقابل نمادها (symbol cross-reference) که به طور پیش‌فرض cscope.out نامیده می‌شود، برای مکان‌یابی توابع، فراخوانی‌های توابع، ماکروها، متغیرها و نمادهای پیش‌پردازنده در فایل‌ها استفاده می‌کند.
.PP
ابزار
.I cscope
پایگاه ارجاع متقابل نمادها را در اولین باری که روی فایل‌های منبع برنامه اجرا می‌شود می‌سازد. در فراخوانی‌های بعدی،
.I cscope
ارجاع متقابل را تنها زمانی بازسازی می‌کند که یک فایل منبع تغییر کرده باشد یا لیست فایل‌های منبع تفاوت کرده باشد. هنگامی که ارجاع متقابل بازسازی می‌شود، داده‌های فایل‌های تغییرنیافته از ارجاع متقابل قدیمی کپی می‌شوند که بازسازی را بسیار سریع‌تر از ساخت اولیه می‌کند.
.SH "گزینه‌ها (OPTIONS)"
برخی از آرگومان‌های خط فرمان تنها می‌توانند به عنوان یگانه آرگومان در اجرای cscope ظاهر شوند. این گزینه‌ها باعث می‌شوند برنامه صرفاً خروجی خاصی را چاپ کرده و فوراً خارج شود:
.TP
.B \-h
نمایش راهنمای کامل نحوه استفاده.
.TP
.B \-V
چاپ شماره نسخه cscope در اولین سطر صفحه نمایش.
.TP
.B \-\-help
مشابه
.B \-h
.TP
.B \-\-version
مشابه
.B \-V

.PP
گزینه‌های زیر می‌توانند در هر ترکیبی ظاهر شوند:
.TP
.B \-b
صرفاً ساخت جدول ارجاع متقابل (بدون ورود به رابط تعاملی).
.TP
.B \-C
نادیده گرفتن بزرگی و کوچکی حروف در هنگام جستجو.
.TP
.B \-c
استفاده تنها از کاراکترهای اسکی در فایل ارجاع متقابل، یعنی داده‌ها فشرده نشوند.
.TP
.B \-d
عدم به‌روزرسانی جدول ارجاع متقابل.
.TP
.B \-e
عدم نمایش اعلان کلید <Ctrl>-e بین فایل‌ها.
.TP
.BI \-F symfile
خواندن خطوط ارجاع نمادها از
.I symfile.
(فایل ارجاع نماد توسط < و >> ایجاد می‌شود و با استفاده از دستور < نیز قابل خواندن است).
.TP
.BI \-f reffile
استفاده از
.I reffile
به عنوان نام فایل ارجاع متقابل به جای پیش‌فرض "cscope.out".
.TP
.BI \-I incdir
جستجو در دایرکتوری
.I incdir
(پیش از جستجو در $INCDIR که محل استاندارد فایل‌های سرآیند و معمولاً /usr/include است) برای فایل‌های #include که نام آن‌ها با "/" شروع نمی‌شود و در خط فرمان یا در
.I namefile
تعیین نشده‌اند. دایرکتوری incdir علاوه بر پوشه جاری و لیست استاندارد جستجو می‌شود.
.TP
.BI \-i namefile
پیمایش تمام فایل‌های منبعی که نام آن‌ها در
.I namefile
فهرست شده است (نام‌های جداشده با فاصله، تب یا خط جدید) به جای فایل پیش‌فرض cscope.files. اگر نام فایل حاوی فاصله است باید درون دو گیومه قرار گیرد.
.TP
.B \-k
حالت هسته ("Kernel Mode")؛ خاموش کردن استفاده از مسیر پیش‌فرض include (معمولاً /usr/include) در زمان ساخت پایگاه داده، زیرا درخت منبع هسته عموماً از آن استفاده نمی‌کند.
.TP
.B \-L
انجام جستجوی تکی با خروجی خط‌محور زمانی که همراه با گزینه -num pattern استفاده شود.
.TP
.B \-l
رابط خط‌محور (Line-oriented interface).
.TP
.BI \-[ "0-9" ] pattern
رفتن به فیلد ورودی
.I num
(شمارش از 0) و یافتن
.I pattern.
.TP
.BI \-P path
افزودن پیشوند
.I path
به مسیرهای نسبی فایل‌ها در فایل ارجاع متقابل از پیش ساخته‌شده. این گزینه تنها همراه با گزینه \-d معتبر است.
.TP
.BI \-p n
نمایش آخرین
.I n
بخش مسیر فایل به جای پیش‌فرض (1). استفاده از
.I 0
باعث عدم نمایش نام فایل می‌شود.
.TP
.B \-q
فعال‌سازی جستجوی سریع نمادها از طریق نمایه معکوس (inverted index). این گزینه موجب ایجاد دو فایل اضافی ("cscope.in.out" و "cscope.po.out") در کنار پایگاه‌داده اصلی می‌شود که سرعت جستجو را در پروژه‌های بزرگ به میزان چشمگیری افزایش می‌دهد.
.TP
.B \-R
جستجوی بازگشتی زیرپوشه‌ها برای یافتن فایل‌های منبع.
.TP
.BI \-s dir
جستجو در
.I dir
برای فایل‌های منبع اضافی.
.TP
.B \-T
استفاده تنها از هشت کاراکتر نخست برای تطبیق با نمادهای C.
.TP
.B \-U
بررسی برچسب زمانی فایل‌ها. برچسب زمانی پایگاه داده را حتی اگر فایلی تغییر نکرده باشد به‌روز می‌کند.
.TP
.B \-u
ساخت بدون قید و شرط فایل ارجاع متقابل (با فرض اینکه تمام فایل‌ها تغییر کرده‌اند).
.TP
.B \-v
حالت پرگو در حالت خط‌محور؛ نمایش گزارش پیشرفت هنگام ساخت پایگاه داده و جستجوها.
.TP
.B \-X
حذف فایل ارجاع cscope و نمایه‌های معکوس در زمان خروج.
.TP
.I files
لیستی از نام فایل‌ها برای پردازش.
.PP
گزینه‌های \-I، \-c، \-k، \-p، \-q و \-T می‌توانند درون فایل cscope.files نیز قرار گیرند.
.PP
.SS "درخواست جستجوی اولیه (Requesting the initial search)"
.PP
پس از آماده شدن ارجاع متقابل، cscope این منو را نمایش می‌دهد:
.PP
.B Find this C symbol:
.PD 0
.TP
.B Find this function definition:
.TP
.B Find functions called by this function:
.TP
.B Find functions calling this function:
.TP
.B Find this text string:
.TP
.B Change this text string:
.TP
.B Find this egrep pattern:
.TP
.B Find this file:
.TP
.B Find files #including this file:
.TP
.B Find assignments to this symbol:
.PD 1
.PP
کلیدهای <Up> یا <Down> را برای حرکت به فیلد ورودی دلخواه فشار دهید، متن مورد نظر برای جستجو را تایپ کرده و سپس کلید <Return> را بفشارید.
.PP
.SS "ارسال درخواست‌های بعدی (Issuing subsequent requests)"
در صورت موفقیت جستجو، هر یک از این دستورات تک‌کاراکتری می‌توانند استفاده شوند:
.TP
.B 0-9a-zA-Z
ویرایش فایل ارجاع داده‌شده با شماره خط مشخص.
.TP
.B <Space>
نمایش مجموعه بعدی خطوط منطبق.
.TP
.B <Tab>
جابجایی بین منو و لیست خطوط منطبق.
.TP
.B <Up>
حرکت به گزینه قبلی منو یا حرکت به خط منطبق قبلی.
.TP
.B <Down>
حرکت به گزینه بعدی منو یا حرکت به خط منطبق بعدی.
.TP
.B +
نمایش مجموعه بعدی خطوط منطبق.
.TP
.B \-
نمایش مجموعه قبلی خطوط منطبق.
.TP
.B ^e
ویرایش فایل‌های نمایش‌داده‌شده به ترتیب.
.TP
.B >
نوشتن لیست خطوط نمایش‌داده‌شده در یک فایل.
.TP
.B >>
الحاق لیست خطوط نمایش‌داده‌شده به یک فایل.
.TP
.B <
خواندن خطوط از یک فایل با قالب ارجاع نماد (ایجادشده با > یا >>)، همانند گزینه \-F.
.TP
.B ^
فیلتر کردن تمام خطوط از طریق یک دستور پوسته و نمایش خطوط حاصل به جای خطوط قبلی.
.TP
.B |
هدایت (pipe) تمام خطوط به یک دستور پوسته و نمایش آن‌ها بدون تغییر.
.PP
در هر زمان این دستورات تک‌کاراکتری نیز قابل استفاده هستند:
.TP
.B <Return>
حرکت به فیلد ورودی بعدی.
.TP
.B ^n
حرکت به فیلد ورودی بعدی.
.TP
.B ^p
حرکت به فیلد ورودی قبلی.
.TP
.B ^y
جستجو با آخرین متن تایپ‌شده.
.TP
.B ^b
حرکت به فیلد ورودی و الگوی جستجوی قبلی.
.TP
.B ^f
حرکت به فیلد ورودی و الگوی جستجوی بعدی.
.TP
.B ^c
تغییر حالت نادیده‌گرفتن/حساسیت به بزرگی و کوچکی حروف در جستجو.
.TP
.B ^r
بازسازی پایگاه ارجاع متقابل.
.TP
.B !
اجرای یک پوسته تعاملی (تایپ ^d برای بازگشت به cscope).
.TP
.B ^l
بازتولید و رسم مجدد صفحه نمایش.
.TP
.B ?
نمایش اطلاعات راهنما درباره دستورات cscope.
.TP
.B ^d
خروج از cscope.
.PP
.PP
.B نکته: اگر کاراکتر اول متن مورد جستجو با یکی از دستورات بالا همخوانی دارد، ابتدا یک بک‌اسلش (\\) تایپ کنید تا اسکیپ شود.
.PP
.B جایگزینی متن جدید به جای متن قدیمی
.PP
پس از وارد کردن متنی که باید تغییر یابد، cscope متن جدید را درخواست می‌کند و سپس خطوط حاوی متن قدیمی را نمایش می‌دهد. خطوط مورد نظر برای تغییر را با این دستورات انتخاب کنید:
.PP
.TP
.B 0-9a-zA-Z
علامت‌گذاری یا لغو علامت خط مورد تغییر.
.TP
.B *
علامت‌گذاری یا لغو علامت تمام خطوط نمایش‌داده‌شده.
.TP
.B <Space>
نمایش مجموعه بعدی خطوط.
.TP
.B +
نمایش مجموعه بعدی خطوط.
.TP
.B \-
نمایش مجموعه قبلی خطوط.
.TP
.B a
علامت‌گذاری یا لغو علامت تمام خطوط مورد نظر برای تغییر.
.TP
.B ^d
تغییر خطوط علامت‌گذاری‌شده و خروج.
.TP
.B <Esc>
خروج بدون تغییر خطوط علامت‌گذاری‌شده.
.TP
.B !
اجرای یک پوسته تعاملی (تایپ ^d برای بازگشت به cscope).
.TP
.B ^l
بازتولید و رسم مجدد صفحه نمایش.
.TP
.B ?
ارائه اطلاعات راهنما درباره دستورات cscope.
.TP
.B کلیدهای ویژه
اگر ترمینال شما کلیدهای جهتی دارد که در vi کار می‌کنند، می‌توانید از آن‌ها برای حرکت در فیلدهای ورودی استفاده کنید. کلیدهای <CLEAR>، <NEXT> یا <PREV> به ترتیب مانند دستورات ^l، + و \- عمل می‌کنند.
.PP
.SS "رابط خط‌محور (Line-Oriented interface)"
.PP
گزینه \-l امکان استفاده از cscope را در جایی که رابط گرافیکی یا تمام‌صفحه مناسب نیست (مثلاً از داخل برنامه‌ای دیگر) فراهم می‌کند.
.PP
هنگامی که cscope آماده باشد با << اعلان می‌دهد که ورودی را با شماره فیلد (شروع از 0) به همراه الگوی جستجو دریافت کند؛ برای مثال "lmain" تعریف تابع main را می‌یابد.
.PP
اگر تنها یک جستجوی منفرد می‌خواهید، به جای گزینه \-l از گزینه‌های \-L و \-num pattern استفاده کنید تا اعلان << ظاهر نشود.
.PP
برای گزینه \-l، برنامه تعداد خطوط ارجاع را چاپ می‌کند:
cscope: 2 lines
.PP
به ازای هر ارجاع یافت‌شده، cscope خطی متشکل از نام فایل، نام تابع، شماره خط و متن خط چاپ می‌کند که با فاصله از هم جدا شده‌اند، مانند:
main.c main 161 main(argc, argv)
.PP
توجه داشته باشید که برخلاف رابط تمام‌صفحه، ویرایشگر متن برای نمایش ارجاع تکی فراخوانی نمی‌شود.
.PP
می‌توانید از دستور c برای تغییر حساسیت به بزرگی و کوچکی حروف استفاده کنید.
.PP
می‌توانید از دستور r برای بازسازی پایگاه‌داده استفاده کنید.
.PP
برنامه cscope در زمان تشخیص پایان فایل (EOF) یا با دریافت کاراکتر "^d" یا "q" در ابتدای خط ورودی خاتمه می‌یابد.
.PP
.SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)"
.TP
.B CSCOPE_EDITOR
جایگزین متغیرهای EDITOR و VIEWER می‌شود.
.TP
.B CSCOPE_LINEFLAG
قالب فلگ شماره سطر برای ویرایشگر شما. به طور پیش‌فرض cscope ویرایشگر را به صورت "editor +N file" فراخوانی می‌کند که N شماره سطر است. برای قالب متفاوت می‌توان از %s به عنوان جایگزین استفاده کرد، مثلاً "\-#%s".
.TP
.B CSCOPE_LINEFLAG_AFTER_FILE
اگر ویرایشگر شما نیاز دارد گزینه شماره خط پس از نام فایل بیاید، این متغیر را برابر "yes" قرار دهید.
.TP
.B EDITOR
ویرایشگر متن ترجیحی که پیش‌فرض آن vi است.
.TP
.B HOME
دایرکتوری خانگی کاربر.
.TP
.B INCLUDEDIRS
لیست دایرکتوری‌های جداشده با دو نقطه برای جستجوی فایل‌های #include.
.TP
.B SHELL
پوسته ترجیحی که پیش‌فرض آن sh است.
.TP
.B SOURCEDIRS
لیست دایرکتوری‌های جداشده با دو نقطه برای جستجوی فایل‌های منبع اضافی.
.TP
.B TERM
نوع ترمینال.
.TP
.B TERMINFO
مسیر کامل دایرکتوری اطلاعات ترمینال terminfo.
.TP
.B TMPDIR
دایرکتوری فایل‌های موقت که پیش‌فرض آن /var/tmp است.
.TP
.B VIEWER
برنامه ترجیحی نمایش فایل (مانند less) که اولویت بالاتری از EDITOR دارد.
.TP
.B VPATH
لیست دایرکتوری‌های جداشده با دونقطه برای مسیر جستجوی فایل‌های منبع.
.PP
.SH "فایل‌ها (FILES)"
.TP
.B cscope.files
فایل پیش‌فرض شامل گزینه‌های \-I، \-p، \-q، \-T و فهرست فایل‌های منبع.
.TP
.B cscope.out
فایل ارجاع متقابل نمادها که در صورت عدم امکان ایجاد در پوشه جاری، در دایرکتوری خانگی ذخیره می‌شود.
.TP
.PD 0
.B cscope.in.out
.TP
.B cscope.po.out
.PD 1
فایل‌های پیش‌فرض حاوی نمایه معکوس برای جستجوی سریع نمادها (گزینه \-q).
.TP
.B INCDIR
دایرکتوری استاندارد برای فایل‌های #include (معمولاً /usr/include).
.SH "نکات و تذکرات (Notices)"
ابزار
.I cscope
تعاریف توابع را با الگوی زیر شناسایی می‌کند:
.PD 0
.TP
fname blank ( args ) white arg_decs white {
.PD 1
.TP
که در آن:
.I fname
نام تابع است
.TP
.I blank
صفر یا چند فاصله، تب، فرم‌فید بدون خط جدید است
.TP
.I args
هر رشته‌ای که شامل گیومه یا خط جدید نباشد
.TP
.I white
صفر یا چند فاصله، تب، فرم‌فید یا خط جدید است
.TP
.I arg_decs
صفر یا چند اعلان آرگومان است
.PP
ضرورتی ندارد اعلان تابع از ابتدای خط شروع شود. نوع برگشتی می‌تواند قبل از نام تابع باشد. تعاریف تابعی که از این الگو پیروی نکنند توسط cscope شناسایی نمی‌شوند.
.PP
ستون "Function" در خروجی جستجو برای گزینه Find functions called by this function تنها اولین تابع فراخوانی‌شده در خط را نمایش می‌دهد.
.PP
گاهی ممکن است تعریف یا فراخوانی یک تابع به دلیل وجود آکولادها درون دستورات #if شناسایی نشود. مشابهاً استفاده از یک متغیر ممکن است به اشتباه به عنوان تعریف آن شناخته شود.
.PP
یک نام
.B typedef
پیش از یک عبارت پیش‌پردازنده ممکن است به اشتباه به عنوان یک تعریف سراسری شناخته شود. عبارات پیش‌پردازنده همچنین می‌توانند مانع از تشخیص یک تعریف سراسری شوند.
.PP
اعلان یک تابع درون یک تابع دیگر به اشتباه به عنوان فراخوانی تابع شناسایی می‌شود.
.PP
ابزار
.I cscope
کلاس‌های C++ را با جستجوی کلمه کلیدی class شناسایی می‌کند، اما ساختار struct را به عنوان کلاس تشخیص نمی‌دهد و تعاریف توابع عضو درون ساختار را نمی‌شناسد. همچنین تعاریف توابع عملگر (operator) و توابع دارای آرگومان اشاره‌گر به تابع را شناسایی نمی‌کند.