SCAN-BUILD(1)               General Commands Manual              SCAN-BUILD(1)

نام (NAME)
     scan-build – تحلیل‌گر ایستای Clang

خلاصه دستور (SYNOPSIS)
     scan-build [-ohkvV] [-analyze-headers] [-enable-checker [checker_name]]
     [-disable-checker [checker_name]] [--help] [--help-checkers]
     [--html-title [=title]] [--keep-going] [-plist] [-plist-html]
     [--status-bugs] [--use-c++ [=compiler_path]] [--use-cc [=compiler_path]]
     [--view] [-constraints [model]] [-maxloop N] [-no-failure-reports]
     [-stats] [-store [model]] build_command [build_options]

توضیحات (DESCRIPTION)
     scan-build یک اسکریپت Perl است که تحلیل‌گر ایستای Clang را فراخوانی می‌کند.
     گزینه‌های مورد استفاده توسط scan-build یا توسط تحلیل‌گر ابتدا می‌آیند، و در
     ادامه build_command و هر build_options که معمولاً برای ساخت سیستم هدف
     استفاده می‌شود، قرار می‌گیرند.

     تحلیل‌گر ایستا از فهرست بلندی از الگوریتم‌های بررسی استفاده می‌کند؛ به
     بررسی‌کننده‌ها (CHECKERS) مراجعه کنید. خروجی را می‌توان در قالب استاندارد
     .plist و/یا HTML نوشت.

     گزینه‌های زیر پشتیبانی می‌شوند:

     -analyze-headers
             توابع موجود در فایل‌های گنجانده‌شده (#included) را نیز تحلیل می‌کند.

     -enable-checker checker_name, -disable-checker checker_name
             فعال/غیرفعال کردن checker_name.  به بررسی‌کننده‌ها (CHECKERS)
             مراجعه کنید.

     -h, --help
             نمایش این پیام راهنما.

     --help-checkers
             فهرست کردن بررسی‌کننده‌های پیش‌فرض؛ به بررسی‌کننده‌ها (CHECKERS)
             مراجعه کنید.

     --html-title[=title]
             مشخص کردن عنوان مورد استفاده در صفحات HTML تولیدشده. اگر title
             مشخص نشود، یک عنوان پیش‌فرض ایجاد می‌شود.

     -k, --keep-going
             افزودن گزینهٔ “ادامه دادن (keep on going)” به build_command.  در
             حال حاضر از make و xcodebuild پشتیبانی می‌کند. این یک گزینهٔ
             تسهیل‌کننده است؛ می‌توان این رفتار را مستقیماً با استفاده از
             گزینه‌های ساخت نیز مشخص کرد.

     -o      دایرکتوری هدف برای فایل‌های گزارش HTML. زیردایرکتوری‌ها بر حسب نیاز
             برای نمایش فراخوانی‌های جداگانهٔ تحلیل‌گر ایجاد خواهند شد. اگر این
             گزینه مشخص نشود، دایرکتوری‌ای در /tmp (متغیر TMPDIR در Mac OS X)
             برای ذخیرهٔ گزارش‌ها ایجاد می‌شود.

     -plist  خروجی دادن نتایج به صورت مجموعه‌ای از فایل‌های .plist.  (به طور
             پیش‌فرض خروجی scan-build مجموعه‌ای از فایل‌های HTML است.)

     -plist-html
             خروجی دادن نتایج به صورت مجموعه‌ای از فایل‌های HTML و .plist.

     --status-bugs
             در صورت یافتن باگ‌های احتمالی وضعیت خروج را روی 1 و در غیر این
             صورت روی 0 تنظیم می‌کند. به طور پیش‌فرض، وضعیت خروج scan-build همان
             مقدار بازگردانده‌شده توسط build_command است.

     --use-c++[=compiler_path]
             حدس زدن کامپایلر پیش‌فرض برای کدهای C++ و Objective-C++. از این
             گزینه برای تعیین یک کامپایلر جایگزین استفاده کنید.

     --use-cc[=compiler_path]
             حدس زدن کامپایلر پیش‌فرض برای کدهای C و Objective-C. از این گزینه
             برای تعیین یک کامپایلر جایگزین استفاده کنید.

     -v      خروجی پرحرّاف (verbose) از scan-build و تحلیل‌گر. آوردن یک v دوم و
             سوم میزان جزئیات خروجی را افزایش می‌دهد.

     -V, --view
             مشاهدهٔ نتایج تحلیل در یک مرورگر وب پس از پایان ساخت.

     -constraints [model]
             تعیین موتور قیود (constraint engine) مورد استفاده توسط تحلیل‌گر.
             به طور پیش‌فرض مدل ‘range’ استفاده می‌شود. تعیین ‘basic’ از یک مدل
             قید ساده‌تر و با قدرت کمتر استفاده می‌کند که در checker-0.160 و
             نگارش‌های پیشین استفاده می‌شد.

     -maxloop N
             تعیین تعداد دفعاتی که یک بلوک پیش از صرف‌نظر کردن می‌تواند پیمایش
             شود. مقدار پیش‌فرض 4 است. برای پوشش جامع‌تر به قیمت کاهش سرعت، این
             مقدار را افزایش دهید.

     -no-failure-reports
             از ایجاد یک زیردایرکتوری ‘failures’ که شامل گزارش‌های خرابی
             (crash) تحلیل‌گر و فایل‌های منبع پیش‌پردازش‌شده است، خودداری می‌کند.

     -stats  تولید آمار پیمایش برای پروژه‌ای که در حال تحلیل است.

     -store [model]
             تعیین مدل ذخیره‌سازی (store model) مورد استفاده توسط تحلیل‌گر. به
             طور پیش‌فرض، مدل ذخیره‌سازی ‘region’ استفاده می‌شود.  ‘region’ یک
             مدل ذخیره‌سازی حساس به فیلد (field-sensitive) را مشخص می‌کند.
             کاربران همچنین می‌توانند ‘basic’ را مشخص کنند که دقت بسیار کمتری
             دارد اما می‌تواند کد را با سرعت بیشتری تحلیل کند.  ‘basic’ مدل
             ذخیره‌سازی پیش‌فرض برای checker-0.221 و پیش از آن بود.

وضعیت خروج (EXIT STATUS)
     scan-build مقدار بازگردانده‌شده توسط build_command را برمی‌گرداند مگر اینکه
     --status-bugs یا --keep-going استفاده شده باشد.

بررسی‌کننده‌ها (CHECKERS)
     بررسی‌کننده‌های فهرست‌شده در زیر را می‌توان با استفاده از گزینه‌های
     -enable-checker و -disable-checker فعال یا غیرفعال کرد.  یک گروه پیش‌فرض
     از بررسی‌کننده‌ها اجرا می‌شوند مگر اینکه صریحاً غیرفعال شده باشند.  اینکه
     دقیقاً کدام بررسی‌کننده‌ها گروه پیش‌فرض را تشکیل می‌دهند وابسته به سیستم‌عامل
     مورد استفاده است؛ این موارد با --help-checkers فهرست می‌شوند.

     core.AdjustedReturnValue
              بررسی می‌کند آیا مقدار بازگشتی یک فراخوانی تابع با آنچه
              فراخواننده انتظار دارد تفاوت دارد یا خیر (برای نمونه، فراخوانی‌ها
              از طریق اشاره‌گرهای تابع).

     core.AttributeNonNull
              بررسی اشاره‌گرهای تهی (null) پاس داده‌شده به عنوان آرگومان به
              تابعی که آرگومان‌های آن با مشخصهٔ ‘nonnull’ علامت‌گذاری شده‌اند.

     core.CallAndMessage
              بررسی خطاهای منطقی در فراخوانی‌های تابع و عبارات پیام Objective-C
              (مانند آرگومان‌های مقداردهی‌نشده، اشاره‌گرهای تابع تهی).

     core.DivideZero
              بررسی تقسیم بر صفر.

     core.NullDereference
              بررسی ارجاع‌زدایی از اشاره‌گرهای تهی.

     core.StackAddressEscape
              بررسی اینکه آدرس‌های حافظهٔ پشته (stack) از تابع خارج نشوند.

     core.UndefinedBinaryOperatorResult
              بررسی نتایج تعریف‌نشده برای عملگرهای دودویی.

     core.VLASize
              بررسی اعلان‌های VLA با اندازهٔ صفر یا تعریف‌نشده.

     core.builtin.BuiltinFunctions
              ارزیابی توابع توکار (builtin) کامپایلر، مانند alloca().

     core.builtin.NoReturnFunctions
              ارزیابی توابع ‘panic’ که مشخص است مقداری را به فراخواننده
              بازنمی‌گردانند.

     core.uninitialized.ArraySubscript
              بررسی مقادیر مقداردهی‌نشده که به عنوان اندیس آرایه استفاده
              شده‌اند.

     core.uninitialized.Assign
              بررسی انتساب مقادیر مقداردهی‌نشده.

     core.uninitialized.Branch
              بررسی مقادیر مقداردهی‌نشده که به عنوان شرط‌های شاخه‌بندی استفاده
              شده‌اند.

     core.uninitialized.CapturedBlockVariable
              بررسی بلوک‌هایی که مقادیر مقداردهی‌نشده را تسخیر (capture) می‌کنند.

     core.uninitialized.UndefReturn
              بررسی مقادیر مقداردهی‌نشده که به فراخواننده بازگردانده می‌شوند.

     deadcode.DeadStores
              بررسی مقادیر ذخیره‌شده در متغیرهایی که پس از آن هرگز خوانده
              نمی‌شوند.

     debug.DumpCFG
              نمایش گراف‌های جریان کنترل (Control-Flow Graphs).

     debug.DumpCallGraph
              نمایش گراف فراخوانی (Call Graph).

     debug.DumpDominators
              چاپ درخت تسلط (dominance tree) برای یک گراف جریان کنترل مشخص.

     debug.DumpLiveVars
              چاپ نتایج تحلیل متغیرهای زنده (live variable analysis).

     debug.Stats
              صدور هشدارها به همراه آمار تحلیل‌گر.

     debug.TaintTest
              علامت‌گذاری نمادهای آلوده (tainted) به عنوان آلوده.

     debug.ViewCFG
              مشاهدهٔ گراف‌های جریان کنترل با استفاده از GraphViz.

     debug.ViewCallGraph
              مشاهدهٔ گراف فراخوانی با استفاده از GraphViz.

     llvm.Conventions
              بررسی کد برای انطباق با قراردادهای پایه‌کد LLVM.

     osx.API  بررسی استفادهٔ صحیح از APIهای مختلف Mac OS X.

     osx.AtomicCAS
              ارزیابی فراخوانی توابع OSAtomic.

     osx.SecKeychainAPI
              بررسی استفادهٔ صحیح از APIهای Secure Keychain.

     osx.cocoa.AtSync
              بررسی اشاره‌گرهای تهی مورد استفاده به عنوان موتکس برای
              @synchronized.

     osx.cocoa.ClassRelease
              بررسی ارسال مستقیم ‘retain ،’ ‘release’ یا ‘autorelease’ به یک
              Class.

     osx.cocoa.IncompatibleMethodTypes
              هشدار دربارهٔ امضای متدهای Objective-C با ناسازگاری‌های نوع داده.

     osx.cocoa.NSAutoreleasePool
              هشدار در مورد استفاده‌های نامطلوب از NSAutoreleasePool در حالت GC
              مربوط به Objective-C.

     osx.cocoa.NSError
              بررسی استفاده از پارامترهای **NSError.

     osx.cocoa.NilArg
              بررسی آرگومان‌های ممنوع nil در فراخوانی‌های متد Objective-C.

     osx.cocoa.RetainCount
              بررسی نشت حافظه و مدیریت نادرست شمارش ارجاع.

     osx.cocoa.SelfInit
              بررسی اینکه ‘self’ درون متد مقداردهی اولیه (initializer) به
              درستی مقداردهی شده باشد.

     osx.cocoa.UnusedIvars
              هشدار دربارهٔ متغیرهای نمونهٔ خصوصی (ivars) که هرگز استفاده
              نمی‌شوند.

     osx.cocoa.VariadicMethodTypes
              بررسی ارسال انواع غیر Objective-C به متدهای با تعداد آرگومان
              متغیر (variadic) که تنها انواع Objective-C را انتظار دارند.

     osx.coreFoundation.CFError
              بررسی استفاده از پارامترهای *CFErrorRef.

     osx.coreFoundation.CFNumber
              بررسی استفادهٔ صحیح از CFNumberCreate().

     osx.coreFoundation.CFRetainRelease
              بررسی آرگومان‌های تهی به CFRetain(،) CFRelease() و
              CFMakeCollectable().

     osx.coreFoundation.containers.OutOfBounds
              بررسی خارج از محدوده بودن اندیس هنگام استفاده از API مربوط به
              CFArray.

     osx.coreFoundation.containers.PointerSizedValues
              هشدار در صورتی که CFArray ، CFDictionary یا CFSet با مقادیری با
              اندازه‌ای غیر از اندازهٔ اشاره‌گر ایجاد شده باشند.

     security.FloatLoopCounter
              هشدار در صورت استفاده از مقدار ممیز شناور به عنوان شمارندهٔ حلقه
              (CERT: FLP30-C, FLP30-CPP).

     security.insecureAPI.UncheckedReturn
              هشدار در مورد استفاده از توابعی که مقادیر بازگشتی آن‌ها همواره
              باید بررسی شوند.

     security.insecureAPI.getpw
              هشدار در مورد استفاده از getpw().

     security.insecureAPI.gets
              هشدار در مورد استفاده از gets().

     security.insecureAPI.mkstemp
              هشدار زمانی که در رشتهٔ قالب mkstemp() کمتر از ۶ نویسهٔ X داده شده
              باشد.

     security.insecureAPI.mktemp
              هشدار در مورد استفاده از mktemp().

     security.insecureAPI.rand
              هشدار در مورد استفاده از rand(،) random() و توابع مرتبط.

     security.insecureAPI.strcpy
              هشدار در مورد استفاده از strcpy() و strcat().

     security.insecureAPI.vfork
              هشدار در مورد استفاده از vfork().

     unix.API
              بررسی فراخوانی‌های توابع مختلف UNIX/Posix.

     unix.Malloc
              بررسی نشت حافظه، آزادسازی دوباره (double free) و استفاده پس از
              آزادسازی (use-after-free).

     unix.cstring.BadSizeArg
              بررسی آرگومان اندازهٔ پاس داده‌شده به توابع رشتهٔ C برای الگوهای
              خطای متداول.

     unix.cstring.NullArg
              بررسی ارسال اشاره‌گرهای تهی به عنوان آرگومان به توابع رشتهٔ C.

مثال‌ها (EXAMPLES)
     scan-build -o /tmp/myhtmldir make -j4

     مثال بالا باعث می‌شود گزارش‌های تحلیل در یک زیردایرکتوری از /tmp/myhtmldir
     قرار گیرند و make با گزینهٔ -j4 اجرا شود.  هر بار که scan-build پروژه‌ای را
     تحلیل می‌کند، یک زیردایرکتوری متفاوت ایجاد می‌شود.  تحلیل‌گر باید از بیشتر
     ساخت‌های موازی پشتیبانی کند، اما از ساخت‌های توزیع‌شده پشتیبانی نمی‌کند.

نویسندگان (AUTHORS)
     scan-build توسط Ted Kremenek نوشته شده است.  مستندات توسط James K. Lowden
     ⟨jklowden@schemamania.org⟩ مشارکت شده است.

clang 20                        August 18, 2024                       clang 20