Основные сведения о языке SAL
Язык аннотирования Microsoft Source-Code (SAL) предоставляет набор заметок, которые можно использовать для описания того, как функция использует ее параметры, предположения, что она делает, и гарантирует, что она делает это после завершения. Заметки определяются в файле <sal.h> заголовка. Visual Studio анализ кода для C++ использует аннотации SAL для изменения его анализа функций. дополнительные сведения о языке sal 2,0 для разработки драйверов Windows см. в разделе примечания sal 2,0 для Windows драйверов.
Изначально C и C++ предоставляют разработчикам только ограниченные способы согласованного определения намерений и расхождений. С помощью аннотаций SAL можно более подробно описать функции, чтобы разработчики, использующие их, могли лучше понять, как их использовать.
Что такое SAL и зачем его использовать?
Говоря просто, SAL является недорогым способом позволить компилятору проверить ваш код.
SAL делает код более ценным
SAL поможет сделать разработку кода более понятной, как для людей, так и для средств анализа кода. Рассмотрим этот пример, в котором показана функция memcpy времени выполнения C:
Можно ли узнать, что делает эта функция? При реализации или вызове функции необходимо поддерживать определенные свойства, чтобы обеспечить правильность программы. Просто взглянув на объявление, такое как в примере, вы не понимаете, что они представляют. Без аннотаций SAL вам пришлось полагаться на документацию или комментарии к коду. Вот как выглядит документация memcpy :
» memcpy копирует число байтов из src в dest; wmemcpy число копий расширенных символов (2 байта). При перекрытии исходного и конечного буферов поведение memcpy не определено. Используйте memmove для обработки перекрывающихся областей.
Важно. Убедитесь, что целевой буфер имеет тот же размер или больше, чем исходный буфер. Дополнительные сведения см. в разделе Предотвращение переполнения буфера.
В документации содержится несколько данных, которые предполагают, что код должен поддерживать определенные свойства для обеспечения правильности программы:
memcpy count копирует байты из исходного буфера в целевой буфер.
Конечный буфер должен быть не меньше размера исходного буфера.
Однако компилятор не может прочитать документацию или неформальные комментарии. Это не знает, что существует связь между двумя буферами и count , а также не может эффективно догадаться о связи. SAL может предоставить более наглядные сведения о свойствах и реализации функции, как показано ниже:
Обратите внимание, что эти заметки похожи на сведения в документации, но они более лаконичны и следуют семантическому шаблону. При чтении этого кода можно быстро понять свойства этой функции и избежать проблем безопасности переполнения буфера. Более того, Семантические шаблоны, предоставляемые SAL, могут повысить эффективность и эффективность автоматизированных средств анализа кода при раннем обнаружении потенциальных ошибок. Imagine, что кто-то пишет эту реализацию wmemcpy ошибками:
Эта реализация содержит общее сообщение об ошибке. К счастью, автор кода включил аннотацию размера буфера SAL — средство анализа кода может перехватить ошибку, анализируя только эту функцию.
Основы SAL
SAL определяет четыре основных типа параметров, которые классифицируются по шаблону использования.
| Категория | Аннотация параметра | Описание |
|---|---|---|
| Входные данные для вызываемой функции | _In_ | Данные передаются в вызываемую функцию и обрабатываются как доступная только для чтения. |
| Вход в вызываемую функцию и вывод в вызывающий объект | _Inout_ | Пригодные для использования данные передаются в функцию и потенциально изменяются. |
| Вывод в вызывающий объект | _Out_ | Вызывающий объект предоставляет только пространство для вызываемой функции для записи. Вызываемая функция записывает данные в это пространство. |
| Вывод указателя на вызывающий объект | _Outptr_ | Как и выходные данные в вызывающий объект. Значение, возвращаемое вызываемой функцией, является указателем. |
Эти четыре основные аннотации можно сделать более явными различными способами. По умолчанию предполагается, что параметры указателей с заметками являются обязательными — они не должны иметь значение NULL, чтобы функция была выполнена. Наиболее часто используемый вариант основных заметок указывает на то, что параметр указателя является необязательным — если он равен NULL, функция может продолжать работать.
В этой таблице показано, как различать обязательные и необязательные параметры.
| Параметры обязательны | Параметры являются необязательными | |
|---|---|---|
| Входные данные для вызываемой функции | _In_ | _In_opt_ |
| Вход в вызываемую функцию и вывод в вызывающий объект | _Inout_ | _Inout_opt_ |
| Вывод в вызывающий объект | _Out_ | _Out_opt_ |
| Вывод указателя на вызывающий объект | _Outptr_ | _Outptr_opt_ |
Эти аннотации помогают определить возможные неинициализированные значения и недопустимые использование пустых указателей в формальном и точном порядке. Передача значения NULL в обязательный параметр может вызвать сбой или привести к возвращению кода ошибки «сбой». В любом случае функция не может быть выполнена в своей работе.
Примеры SAL
В этом разделе приведены примеры кода для базовых аннотаций SAL.
использование средства анализа Visual Studio Code для поиска дефектов
в примерах средство анализа Visual Studio Code используется вместе с аннотациями SAL для поиска дефектов кода. Вот как это сделать.
использование средств анализа кода Visual Studio и SAL
в Visual Studio откройте проект C++, содержащий аннотации SAL.
в строке меню выберите сборка, запустите Code Analysis для решения.
Рассмотрим пример _In_ в этом разделе. При выполнении анализа кода на нем отображается следующее предупреждение:
C6387 недопустимое значение параметра «команду» может быть «0»: это не соответствует спецификации функции «uncalled».
Пример. Аннотация _In_
_In_ Заметка указывает на следующее:
Параметр должен быть допустимым и не будет изменяться.
Функция будет считывать только из одноэлементного буфера.
Вызывающий объект должен предоставить буфер и инициализировать его.
_In_ Указывает «только для чтения». Распространенной ошибкой является применение _In_ к параметру, который вместо этого должен иметь _Inout_ заметку.
_In_ параметр разрешен, но игнорируется анализатором для скаляров, не являющихся указателями.
при использовании Visual Studio Code анализа в этом примере проверяется, что вызывающие объекты передают указатель, отличный от Null, в инициализированный буфер для pInt . В этом случае pInt указатель не может иметь значение null.
Пример: _In_opt_ Аннотация
_In_opt_ тот же, что _In_ и, за исключением того, что входной параметр может иметь значение null, поэтому функция должна проверить это.
Visual Studio Codeный анализ проверяет, что функция проверяет наличие значения NULL перед обращением к буферу.
Пример. Аннотация _Out_
_Out_ поддерживает общий сценарий, в котором передается указатель, не имеющий значения NULL, указывающий на буфер элемента, а функция инициализирует элемент. Вызывающему объекту не нужно инициализировать буфер перед вызовом; вызываемая функция обещает инициализировать ее перед возвратом.
средство анализа Visual Studio Code проверит, что вызывающий объект передает указатель, отличный от NULL, в буфер для pInt и что буфер инициализируется функцией перед возвратом.
Пример: _Out_opt_ Аннотация
_Out_opt_ то же самое, что _Out_ и, за исключением того, что параметру может быть присвоено значение null, поэтому функция должна проверить это.
Visual Studio Codeный анализ проверяет, что эта функция проверяет наличие значения NULL перед pInt разыменованием, и если pInt не имеет значение null, то буфер инициализируется функцией перед возвратом.
Пример. Аннотация _Inout_
_Inout_ используется для добавления примечания к параметру указателя, который может быть изменен функцией. Указатель должен указывать на допустимые инициализированные данные перед вызовом, и даже если он изменяется, он по-прежнему должен иметь допустимое значение для возврата. Заметка указывает, что функция может свободно считывать из буфера с одним элементом и записывать в него. Вызывающий объект должен предоставить буфер и инициализировать его.
Like _Out_ , _Inout_ должен применяться к изменяемому значению.
Visual Studio Codeный анализ проверяет, что вызывающие объекты передают указатель, отличный от null, в инициализированный буфер для pInt , и что перед возвратом pInt все еще имеет значение, отличное от null, и буфер инициализируется.
Пример: _Inout_opt_ Аннотация
_Inout_opt_ тот же, что _Inout_ и, за исключением того, что входной параметр может иметь значение null, поэтому функция должна проверить это.
Visual Studio Codeный анализ проверяет, что эта функция проверяет наличие значения NULL перед обращением к буферу, и если pInt не имеет значение null, то буфер инициализируется функцией перед возвратом.
Пример. Аннотация _Outptr_
_Outptr_ используется для аннотации параметра, который должен возвращать указатель. Сам параметр не должен иметь значение NULL, а вызываемая функция возвращает в нее указатель, отличный от NULL, и этот указатель указывает на инициализированные данные.
Visual Studio Codeный анализ проверяет, что вызывающий объект передает указатель, отличный от NULL, для *pInt , и что буфер инициализируется функцией перед возвратом.
Пример: _Outptr_opt_ Аннотация
_Outptr_opt_ то же самое, что _Outptr_ и, за исключением того, что параметр является необязательным — вызывающий объект может передать пустой указатель для параметра.
Visual Studio Codeный анализ проверяет, что эта функция проверяет наличие значения NULL перед *pInt разыменованием, и что буфер инициализируется функцией перед возвратом.
Пример. Аннотация _Success_ в сочетании с _Out_
Заметки можно применять к большинству объектов. В частности, можно закомментировать всю функцию. Одной из самых очевидных характеристик функции является то, что она может завершиться успешно или неудачно. Но, как и в связи между буфером и его размером, C/C++ не может выражать успешную или неудачную работу функции. С помощью _Success_ аннотации можно сказать, как выглядит успешная функция. Параметром для _Success_ заметки является просто выражение, которое, если оно равно true, указывает, что функция выполнена успешно. Выражение может быть любым, которое может обрабатывать средство синтаксического анализа заметок. Эффекты заметок после возврата функции применимы только в случае, если функция выполнена. В этом примере показано, как _Success_ взаимодействует с _Out_ , чтобы выполнить нужное действие. Для представления возвращаемого значения можно использовать ключевое слово return .
_Out_ заметка приводит к тому, что Visual Studio Codeный анализ проверит, что вызывающий объект передает указатель, отличный от NULL, в буфер для pInt и что буфер инициализируется функцией перед возвратом.
Рекомендации по SAL
Добавление заметок к существующему коду
SAL — это мощная технология, которая может помочь повысить безопасность и надежность кода. После изучения SAL можно применить новые навыки к повседневной работе. В новом коде спецификации на основе SAL можно использовать по принципу разработки. в старом коде можно добавлять заметки постепенно и таким образом повышать их преимущества при каждом обновлении.
У общедоступных заголовков Майкрософт уже есть аннотации. Поэтому мы рекомендуем использовать в своих проектах, что сначала закомментировать функции и функции конечных узлов, вызывающие API-интерфейсы Win32, чтобы получить наибольшее преимущество.
Когда делать аннотации?
Ниже приведены некоторые рекомендации.
Закомментировать все параметры указателя.
закомментировать заметки диапазона значений, чтобы Code Analysis могли обеспечить безопасность буфера и указателя.
Закомментировать правила блокировки и блокировать побочные эффекты. Дополнительные сведения см. в разделе Аннотирование режима блокировки.
Добавление заметка к свойствам драйвера и другим свойствам, зависящим от домена.
Кроме того, можно добавить заметки ко всем параметрам, чтобы сделать свою намерение понятной, чтобы упростить проверку выполнения заметок.
Что такое sal
• ___ Agron (Marc Anthony's role in The Capeman) • ___ ammoniac • ___ ammoniac (mineral found around volcanic vents) • ___ Bando, former A's third bas. смотреть
sāl, salis m. (в sg. изредка Vr , Lcr n.)1) соль (s. fossicius или fossĭlis Vr; s. marinus Vr); pl. крупинки соли, соль Vr, Col addito grano salis PM —. смотреть
I -en, -er 1) зал 2) гостиная, салон II -en, -er 1) седло lette (kaste — , vippe) én av salen:а) выбить кого-л. из седла (тж. перен.) б) одолеть прот. смотреть
Sal: übersetzungI Sal, Geologie: das Sial. II Sạl, eine der Kapverd. Inseln, 216 km2, 7 700 Einwohner; mit dem internationalen Flughafen d. смотреть
sal — Yanalif2 сал — Кириллица 1. сущ.плот 2. прил.плотовой ▪ sal ağızu лесосплав ▪ sal ağızuçı плотовщик, плотовод ▪ sal bәylәwçe плотильщик ▪ sal qu. смотреть
1) межд. эк., фин. сокр. от structural adjustment loan2) межд. эк., фин. сокр. от structural adjustment lending3) страх. сокр. от single article limit. смотреть
= -selобразует от имен существительных относительные прилагательныеkut — счастьеkutsal — счастливыйgök — небоgöksel — небесный
m1) соль sal marinho — морская сольsal de cozinha — поваренная сольsal-gema — каменная сольsal amargo (inglês) — английская соль2) прн острота, остроум. смотреть
Sal: translation Sal f, m 1 (f.) English: short form of SALLY (SEE Sally). 2 (m.) U.S.: short form of Spanish SALVADOR (SEE Salvador) or its Italian c. смотреть
1) бот. сал, шорея кистевая (Shorea robusta) 2) растительность, не развивающаяся до уровня климакса вследствие частых пожаров * * *• растительность, не. смотреть
SAL: translation See: Structural Adjustment Loan Facility * * * Spanish company title: abbreviation of Sociedad Anonima Laboral.
скор. від Structural Adjustment Loan
Что такое sal
Англо-русский словарь технических аббревиатур . 2011 .
Смотреть что такое «SAL» в других словарях:
sal — (Del lat. sal). 1. f. Sustancia ordinariamente blanca, cristalina, de sabor propio bien señalado, muy soluble en agua, crepitante en el fuego y que se emplea para sazonar los alimentos y conservar las carnes muertas. Es el cloruro sódico; abunda… … Diccionario de la lengua española
SAL — steht als Abkürzung für: Flughafen San Salvador, IATA Code des Flughafens Landtag des Saarlandes, als Kraftfahrzeugkennzeichen Society of Antiquaries of London, älteste antiquarische Gesellschaft der Welt Sonderausschuss Landwirtschaft, ein… … Deutsch Wikipedia
sal — sustantivo femenino 1. (no contable) Cloruro de sodio. Sustancia blanca y cristalina que abunda en la naturaleza, en yacimientos o disuelta en el mar, y se utiliza para condimentar o para conservar los alimentos, así como en la industria química … Diccionario Salamanca de la Lengua Española
Sal — steht als Abkürzung für: Landtag des Saarlandes, als Kraftfahrzeugkennzeichen Society of Antiquaries of London, älteste antiquarische Gesellschaft der Welt Sonderausschuss Landwirtschaft, ein Komitee zur Vorbereitung der Tagungen des… … Deutsch Wikipedia
sal- — sal English meaning: salt; salty water Deutsche Übersetzung: ‘salz, Seesalz” Grammatical information: nom. sal , sal d , sal i, sal u; gen. sal n és Note: Root sal : salt; salty water derived from Root sū ro , sou ro : salty,… … Proto-Indo-European etymological dictionary
Sal — or SAL may refer to:Names or words* Sal , someone s name, Salvador. A name commonly used by Mexicans. Meaning Savior in English, so in other words another name for Jesus [citation needed] . Commonly abbreviated to Sal in countries where spanish… … Wikipedia
şal — ŞAL, şaluri, s.n. 1. Ţesătură din lână, mătase etc., de diverse forme şi dimensiuni, împodobită cu desene, broderii sau franjuri, pe care femeile o poartă pe cap sau pe umeri. ♦ Fular. 2. (înv.) Stofă fină de lână, fabricată în Orient. ♦ Fâşie… … Dicționar Român
sal-2 — sal 2 English meaning: dirty grey; salt, saliva, willow Deutsche Übersetzung: ‘schmutziggrau” Note: also (after the paint, color) zur Bezeichnung of Salzes (see sal 1), the Grauweide and of Speichels Note: Root sal 2 : dirty… … Proto-Indo-European etymological dictionary
sal — s. m. 1. Substância dura, solúvel, friável, seca, composta de cloreto de sódio, empregada como tempero. = SAL DE COZINHA 2. [Química] Combinação de um ácido com uma base. 3. [Figurado] Malícia que um dito ou escrito encerra. = CHISTE… … Dicionário da Língua Portuguesa
Sal — Sal, eine Ableitungssylbe für Hauptwörter, welche zu dem Hauptworte Sahl gehöret, aber doch nicht überall einerley Bedeutung hat. 1) In dem Oberdeutschen Rinnsal, das Bett eines Flusses, ist es ohne Zweifel noch das alte Sahl, ein Fluß, Canal,… … Grammatisch-kritisches Wörterbuch der Hochdeutschen Mundart