.\" Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
.\" See https://llvm.org/LICENSE.txt for license information.
.\" SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
.\" $Id$
.Dd Aug 18, 2024
.Dt SCAN-BUILD 1
.Os "clang" "20"
.Sh "نام (NAME)"
.Nm scan-build
.Nd تحلیل‌گر ایستای Clang
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Fl ohkvV
.Op Fl analyze-headers
.Op Fl enable-checker Op Ar checker_name
.Op Fl disable-checker Op Ar checker_name
.Op Fl Fl help
.Op Fl Fl help-checkers
.Op Fl Fl html-title Op Ar =title
.Op Fl Fl keep-going
.Op Fl plist
.Op Fl plist-html
.Op Fl Fl status-bugs
.Op Fl Fl use-c++ Op Ar =compiler_path
.Op Fl Fl use-cc Op Ar =compiler_path
.Op Fl Fl view
.Op Fl constraints Op Ar model
.Op Fl maxloop Ar N
.Op Fl no-failure-reports
.Op Fl stats
.Op Fl store Op Ar model
.Ar build_command
.Op build_options
.\"
.\" Sh DESCRIPTION
.Sh "توضیحات (DESCRIPTION)"
.Nm
یک اسکریپت Perl است که تحلیل‌گر ایستای Clang را فراخوانی می‌کند. گزینه‌های مورد استفاده توسط
.Nm
یا توسط تحلیل‌گر ابتدا می‌آیند، و در ادامه
.Ar build_command
و هر
.Ar build_options
که معمولاً برای ساخت سیستم هدف استفاده می‌شود، قرار می‌گیرند.
.Pp
تحلیل‌گر ایستا از فهرست بلندی از الگوریتم‌های بررسی استفاده می‌کند؛ به
.Sx "بررسی‌کننده‌ها (CHECKERS)"
مراجعه کنید. خروجی را می‌توان در قالب استاندارد
.Li .plist
و/یا HTML نوشت.
.Pp
گزینه‌های زیر پشتیبانی می‌شوند:
.Bl -tag -width indent
.It Fl analyze-headers
توابع موجود در فایل‌های گنجانده‌شده (#included) را نیز تحلیل می‌کند.
.It Fl enable-checker Ar checker_name , Fl disable-checker Ar checker_name
فعال/غیرفعال کردن
.Ar checker_name .
به
.Sx "بررسی‌کننده‌ها (CHECKERS)"
مراجعه کنید.
.It Fl h , Fl Fl help
نمایش این پیام راهنما.
.It Fl Fl help-checkers
فهرست کردن بررسی‌کننده‌های پیش‌فرض؛ به
.Sx "بررسی‌کننده‌ها (CHECKERS)"
مراجعه کنید.
.It Fl Fl html-title Ns Op = Ns Ar title
مشخص کردن عنوان مورد استفاده در صفحات HTML تولیدشده. اگر
.Ar title
مشخص نشود، یک عنوان پیش‌فرض ایجاد می‌شود.
.It Fl k , Fl Fl keep-going
افزودن گزینهٔ
.Dq ادامه دادن (keep on going)
به
.Ar build_command .
در حال حاضر از make و xcodebuild پشتیبانی می‌کند. این یک گزینهٔ تسهیل‌کننده است؛ می‌توان این رفتار را مستقیماً با استفاده از گزینه‌های ساخت نیز مشخص کرد.
.It Fl o
دایرکتوری هدف برای فایل‌های گزارش HTML. زیردایرکتوری‌ها بر حسب نیاز برای نمایش فراخوانی‌های جداگانهٔ تحلیل‌گر ایجاد خواهند شد. اگر این گزینه مشخص نشود، دایرکتوری‌ای در /tmp (متغیر TMPDIR در Mac OS X) برای ذخیرهٔ گزارش‌ها ایجاد می‌شود.
.It Fl plist
خروجی دادن نتایج به صورت مجموعه‌ای از فایل‌های
.Li .plist .
(به طور پیش‌فرض خروجی
.Nm
مجموعه‌ای از فایل‌های HTML است.)
.It Fl plist-html
خروجی دادن نتایج به صورت مجموعه‌ای از فایل‌های HTML و .plist.
.It Fl Fl status-bugs
در صورت یافتن باگ‌های احتمالی وضعیت خروج را روی 1 و در غیر این صورت روی 0 تنظیم می‌کند. به طور پیش‌فرض، وضعیت خروج
.Nm
همان مقدار بازگردانده‌شده توسط
.Ar build_command
است.
.It Fl Fl use-c++ Ns Op = Ns Ar compiler_path
حدس زدن کامپایلر پیش‌فرض برای کدهای C++ و Objective-C++. از این گزینه برای تعیین یک کامپایلر جایگزین استفاده کنید.
.It Fl Fl use-cc Ns Op = Ns Ar compiler_path
حدس زدن کامپایلر پیش‌فرض برای کدهای C و Objective-C. از این گزینه برای تعیین یک کامپایلر جایگزین استفاده کنید.
.It Fl v
خروجی پرحرّاف (verbose) از
.Nm
و تحلیل‌گر. آوردن یک
.Ar v
دوم و سوم میزان جزئیات خروجی را افزایش می‌دهد.
.It Fl V , Fl Fl view
مشاهدهٔ نتایج تحلیل در یک مرورگر وب پس از پایان ساخت.
.It Fl constraints Op Ar model
تعیین موتور قیود (constraint engine) مورد استفاده توسط تحلیل‌گر. به طور پیش‌فرض مدل
.Ql range
استفاده می‌شود. تعیین
.Ql basic
از یک مدل قید ساده‌تر و با قدرت کمتر استفاده می‌کند که در checker-0.160 و نگارش‌های پیشین استفاده می‌شد.
.It Fl maxloop Ar N
تعیین تعداد دفعاتی که یک بلوک پیش از صرف‌نظر کردن می‌تواند پیمایش شود. مقدار پیش‌فرض 4 است. برای پوشش جامع‌تر به قیمت کاهش سرعت، این مقدار را افزایش دهید.
.It Fl no-failure-reports
از ایجاد یک زیردایرکتوری
.Ql failures
که شامل گزارش‌های خرابی (crash) تحلیل‌گر و فایل‌های منبع پیش‌پردازش‌شده است، خودداری می‌کند.
.It Fl stats
تولید آمار پیمایش برای پروژه‌ای که در حال تحلیل است.
.It Fl store Op Ar model
تعیین مدل ذخیره‌سازی (store model) مورد استفاده توسط تحلیل‌گر. به طور پیش‌فرض، مدل ذخیره‌سازی
.Ql region
استفاده می‌شود.
.Ql region
یک مدل ذخیره‌سازی حساس به فیلد (field-sensitive) را مشخص می‌کند. کاربران همچنین می‌توانند
.Ql basic
را مشخص کنند که دقت بسیار کمتری دارد اما می‌تواند کد را با سرعت بیشتری تحلیل کند.
.Ql basic
مدل ذخیره‌سازی پیش‌فرض برای checker-0.221 و پیش از آن بود.
.\"
.El
.Sh "وضعیت خروج (EXIT STATUS)"
.Nm
مقدار بازگردانده‌شده توسط
.Ar build_command
را برمی‌گرداند مگر اینکه
.Fl Fl status-bugs
یا
.Fl Fl keep-going
استفاده شده باشد.
.\"
.\" Other sections not yet used ...
.\" .Sh ENVIRONMENT
.\" .Sh FILES
.\" .Sh DIAGNOSTICS
.\" .Sh COMPATIBILITY
.\" .Sh HISTORY
.\" .Sh BUGS
.\"
.Sh "بررسی‌کننده‌ها (CHECKERS)"
بررسی‌کننده‌های فهرست‌شده در زیر را می‌توان با استفاده از گزینه‌های
.Fl enable-checker
و
.Fl disable-checker
فعال یا غیرفعال کرد.
یک گروه پیش‌فرض از بررسی‌کننده‌ها اجرا می‌شوند مگر اینکه صریحاً غیرفعال شده باشند.
اینکه دقیقاً کدام بررسی‌کننده‌ها گروه پیش‌فرض را تشکیل می‌دهند وابسته به سیستم‌عامل مورد استفاده است؛ این موارد با
.Fl Fl help-checkers
فهرست می‌شوند.
.Bl -tag -width indent.
.It core.AdjustedReturnValue
بررسی می‌کند آیا مقدار بازگشتی یک فراخوانی تابع با آنچه فراخواننده انتظار دارد تفاوت دارد یا خیر (برای نمونه، فراخوانی‌ها از طریق اشاره‌گرهای تابع).
.It core.AttributeNonNull
بررسی اشاره‌گرهای تهی (null) پاس داده‌شده به عنوان آرگومان به تابعی که آرگومان‌های آن با مشخصهٔ
.Ql nonnull
علامت‌گذاری شده‌اند.
.It core.CallAndMessage
بررسی خطاهای منطقی در فراخوانی‌های تابع و عبارات پیام Objective-C (مانند آرگومان‌های مقداردهی‌نشده، اشاره‌گرهای تابع تهی).
.It core.DivideZero
بررسی تقسیم بر صفر.
.It core.NullDereference
بررسی ارجاع‌زدایی از اشاره‌گرهای تهی.
.It core.StackAddressEscape
بررسی اینکه آدرس‌های حافظهٔ پشته (stack) از تابع خارج نشوند.
.It core.UndefinedBinaryOperatorResult
بررسی نتایج تعریف‌نشده برای عملگرهای دودویی.
.It core.VLASize
بررسی اعلان‌های VLA با اندازهٔ صفر یا تعریف‌نشده.
.It core.builtin.BuiltinFunctions
ارزیابی توابع توکار (builtin) کامپایلر، مانند
.Fn alloca .
.It core.builtin.NoReturnFunctions
ارزیابی توابع
.Ql panic
که مشخص است مقداری را به فراخواننده بازنمی‌گردانند.
.It core.uninitialized.ArraySubscript
بررسی مقادیر مقداردهی‌نشده که به عنوان اندیس آرایه استفاده شده‌اند.
.It core.uninitialized.Assign
بررسی انتساب مقادیر مقداردهی‌نشده.
.It core.uninitialized.Branch
بررسی مقادیر مقداردهی‌نشده که به عنوان شرط‌های شاخه‌بندی استفاده شده‌اند.
.It core.uninitialized.CapturedBlockVariable
بررسی بلوک‌هایی که مقادیر مقداردهی‌نشده را تسخیر (capture) می‌کنند.
.It core.uninitialized.UndefReturn
بررسی مقادیر مقداردهی‌نشده که به فراخواننده بازگردانده می‌شوند.
.It deadcode.DeadStores
بررسی مقادیر ذخیره‌شده در متغیرهایی که پس از آن هرگز خوانده نمی‌شوند.
.It debug.DumpCFG
نمایش گراف‌های جریان کنترل (Control-Flow Graphs).
.It debug.DumpCallGraph
نمایش گراف فراخوانی (Call Graph).
.It debug.DumpDominators
چاپ درخت تسلط (dominance tree) برای یک گراف جریان کنترل مشخص.
.It debug.DumpLiveVars
چاپ نتایج تحلیل متغیرهای زنده (live variable analysis).
.It debug.Stats
صدور هشدارها به همراه آمار تحلیل‌گر.
.It debug.TaintTest
علامت‌گذاری نمادهای آلوده (tainted) به عنوان آلوده.
.It debug.ViewCFG
مشاهدهٔ گراف‌های جریان کنترل با استفاده از
.Ic GraphViz .
.It debug.ViewCallGraph
مشاهدهٔ گراف فراخوانی با استفاده از
.Ic GraphViz .
.It llvm.Conventions
بررسی کد برای انطباق با قراردادهای پایه‌کد LLVM.
.It osx.API
بررسی استفادهٔ صحیح از APIهای مختلف Mac OS X.
.It osx.AtomicCAS
ارزیابی فراخوانی توابع
.Vt OSAtomic .
.It osx.SecKeychainAPI
بررسی استفادهٔ صحیح از APIهای Secure Keychain.
.It osx.cocoa.AtSync
بررسی اشاره‌گرهای تهی مورد استفاده به عنوان موتکس برای @synchronized.
.It osx.cocoa.ClassRelease
بررسی ارسال مستقیم
.Ql retain ،
.Ql release
یا
.Ql autorelease
به یک Class.
.It osx.cocoa.IncompatibleMethodTypes
هشدار دربارهٔ امضای متدهای Objective-C با ناسازگاری‌های نوع داده.
.It osx.cocoa.NSAutoreleasePool
هشدار در مورد استفاده‌های نامطلوب از
.Vt NSAutoreleasePool
در حالت GC مربوط به Objective-C.
.It osx.cocoa.NSError
بررسی استفاده از پارامترهای **NSError.
.It osx.cocoa.NilArg
بررسی آرگومان‌های ممنوع nil در فراخوانی‌های متد Objective-C.
.It osx.cocoa.RetainCount
بررسی نشت حافظه و مدیریت نادرست شمارش ارجاع.
.It osx.cocoa.SelfInit
بررسی اینکه
.Ql self
درون متد مقداردهی اولیه (initializer) به درستی مقداردهی شده باشد.
.It osx.cocoa.UnusedIvars
هشدار دربارهٔ متغیرهای نمونهٔ خصوصی (ivars) که هرگز استفاده نمی‌شوند.
.It osx.cocoa.VariadicMethodTypes
بررسی ارسال انواع غیر Objective-C به متدهای با تعداد آرگومان متغیر (variadic) که تنها انواع Objective-C را انتظار دارند.
.It osx.coreFoundation.CFError
بررسی استفاده از پارامترهای *CFErrorRef.
.It osx.coreFoundation.CFNumber
بررسی استفادهٔ صحیح از
.Fn CFNumberCreate .
.It osx.coreFoundation.CFRetainRelease
بررسی آرگومان‌های تهی به
.Fn CFRetain ،
.Fn CFRelease
و
.Fn CFMakeCollectable .
.It osx.coreFoundation.containers.OutOfBounds
بررسی خارج از محدوده بودن اندیس هنگام استفاده از API مربوط به
.Vt CFArray .
.It osx.coreFoundation.containers.PointerSizedValues
هشدار در صورتی که
.Vt CFArray ،
.Vt CFDictionary
یا
.Vt CFSet
با مقادیری با اندازه‌ای غیر از اندازهٔ اشاره‌گر ایجاد شده باشند.
.It security.FloatLoopCounter
هشدار در صورت استفاده از مقدار ممیز شناور به عنوان شمارندهٔ حلقه (CERT: FLP30-C, FLP30-CPP).
.It security.insecureAPI.UncheckedReturn
هشدار در مورد استفاده از توابعی که مقادیر بازگشتی آن‌ها همواره باید بررسی شوند.
.It security.insecureAPI.getpw
هشدار در مورد استفاده از
.Fn getpw .
.It security.insecureAPI.gets
هشدار در مورد استفاده از
.Fn gets .
.It security.insecureAPI.mkstemp
هشدار زمانی که در رشتهٔ قالب
.Fn mkstemp
کمتر از ۶ نویسهٔ X داده شده باشد.
.It security.insecureAPI.mktemp
هشدار در مورد استفاده از
.Fn mktemp .
.It security.insecureAPI.rand
هشدار در مورد استفاده از
.Fn rand ،
.Fn random
و توابع مرتبط.
.It security.insecureAPI.strcpy
هشدار در مورد استفاده از
.Fn strcpy
و
.Fn strcat .
.It security.insecureAPI.vfork
هشدار در مورد استفاده از
.Fn vfork .
.It unix.API
بررسی فراخوانی‌های توابع مختلف UNIX/Posix.
.It unix.Malloc
بررسی نشت حافظه، آزادسازی دوباره (double free) و استفاده پس از آزادسازی (use-after-free).
.It unix.cstring.BadSizeArg
بررسی آرگومان اندازهٔ پاس داده‌شده به توابع رشتهٔ C برای الگوهای خطای متداول.
.It unix.cstring.NullArg
بررسی ارسال اشاره‌گرهای تهی به عنوان آرگومان به توابع رشتهٔ C.
.El
.\"
.Sh "مثال‌ها (EXAMPLES)"
.Ic scan-build -o /tmp/myhtmldir make -j4
.Pp
مثال بالا باعث می‌شود گزارش‌های تحلیل در یک زیردایرکتوری از
.Pa /tmp/myhtmldir
قرار گیرند و
.Ic make
با گزینهٔ
.Fl j4
اجرا شود.
هر بار که
.Nm
پروژه‌ای را تحلیل می‌کند، یک زیردایرکتوری متفاوت ایجاد می‌شود.
تحلیل‌گر باید از بیشتر ساخت‌های موازی پشتیبانی کند، اما از ساخت‌های توزیع‌شده پشتیبانی نمی‌کند.
.Sh "نویسندگان (AUTHORS)"
.Nm
توسط
.An "Ted Kremenek"
نوشته شده است.
مستندات توسط
.An "James K. Lowden" Aq jklowden@schemamania.org
مشارکت شده است.