نام (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⟩ مشارکت شده است.