Meaning of __in , __out, __in_opt

Question

What is the meaning of these keywords used before variables in a function parameters?

• __in
• __out
• __in_opt

Answer 1

Those are some of the older decoration macro's from Microsoft's SAL Annotations (the newer ones now follow different casing, starting with a capital, like _In_, _Out_, _In_opt_). These have no real affect on compilation (under VS 2010 they aren't even expanded), they are there for inline API documentation.

1. __in: this parameter is an input to the function (read-only, caller initialized).
2. __out: this parameter contains output from the function when it returns (write-only, caller initialized).
3. __in_opt: a compound annotation formed from _in and _opt, _opt indications that the parameter is optional and can be set to a default value (generally NULL).

You can get the full explanation here of the older decorations here.

Answer 2

As answered by Nercolis, these are SAL annotation attributes. However, these aren't just internal or just for API documentation. The real purpose is for Code Analysis. When you build the project with /analyze compiler option (Project Properties, Code Analysis -> General), these play important role in finding the coding issues.

For example, if a particular pointer argument says __in then it must not be passed a null pointer. The function will not check for null and may cause SEH. __in_opt argument may be null. When compiler finds some issue, it reports it as a warning. See this article.