[akhaldi] 58511: [CRT] * Annotate stdlib_s.h. * Annotate more functions in stdlib.h.

Author: akhaldi
Date: Fri Mar 15 22:04:05 2013
New Revision: 58511

URL: http://svn.reactos.org/svn/reactos?rev=58511&view=rev
Log:
[CRT]
* Annotate stdlib_s.h.
* Annotate more functions in stdlib.h.

Modified:
    trunk/reactos/include/crt/sec_api/stdlib_s.h
    trunk/reactos/include/crt/stdlib.h

Modified: trunk/reactos/include/crt/sec_api/stdlib_s.h
URL: http://svn.reactos.org/svn/reactos/trunk/reactos/include/crt/sec_api/stdlib_...
==============================================================================
--- trunk/reactos/include/crt/sec_api/stdlib_s.h [iso-8859-1] (original)
+++ trunk/reactos/include/crt/sec_api/stdlib_s.h [iso-8859-1] Fri Mar 15 22:04:05 2013
@@ -14,50 +14,330 @@
 extern "C" {
 #endif

-  _CRTIMP errno_t __cdecl _dupenv_s(char **_PBuffer,size_t *_PBufferSizeInBytes,const char *_VarName);
-  _CRTIMP errno_t __cdecl _itoa_s(int _Value,char *_DstBuf,size_t _Size,int _Radix);
-  _CRTIMP errno_t __cdecl _i64toa_s(__int64 _Val,char *_DstBuf,size_t _Size,int _Radix);
-  _CRTIMP errno_t __cdecl _ui64toa_s(unsigned __int64 _Val,char *_DstBuf,size_t _Size,int _Radix);
-  _CRTIMP errno_t __cdecl _ltoa_s(long _Val,char *_DstBuf,size_t _Size,int _Radix);
-  _CRTIMP errno_t __cdecl mbstowcs_s(size_t *_PtNumOfCharConverted,wchar_t *_DstBuf,size_t _SizeInWords,const char *_SrcBuf,size_t _MaxCount);
-  _CRTIMP errno_t __cdecl _mbstowcs_s_l(size_t *_PtNumOfCharConverted,wchar_t *_DstBuf,size_t _SizeInWords,const char *_SrcBuf,size_t _MaxCount,_locale_t _Locale);
-  _CRTIMP errno_t __cdecl _ultoa_s(unsigned long _Val,char *_DstBuf,size_t _Size,int _Radix);
-  _CRTIMP errno_t __cdecl _wctomb_s_l(int *_SizeConverted,char *_MbCh,size_t _SizeInBytes,wchar_t _WCh,_locale_t _Locale);
-  _CRTIMP errno_t __cdecl wcstombs_s(size_t *_PtNumOfCharConverted,char *_Dst,size_t _DstSizeInBytes,const wchar_t *_Src,size_t _MaxCountInBytes);
-  _CRTIMP errno_t __cdecl _wcstombs_s_l(size_t *_PtNumOfCharConverted,char *_Dst,size_t _DstSizeInBytes,const wchar_t *_Src,size_t _MaxCountInBytes,_locale_t _Locale);
+  _Check_return_opt_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _dupenv_s(
+    _Outptr_result_buffer_maybenull_(*_PBufferSizeInBytes) _Outptr_result_z_ char **_PBuffer,
+    _Out_opt_ size_t *_PBufferSizeInBytes,
+    _In_z_ const char *_VarName);
+
+  _Check_return_opt_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _itoa_s(
+    _In_ int _Value,
+    _Out_writes_z_(_Size) char *_DstBuf,
+    _In_ size_t _Size,
+    _In_ int _Radix);
+
+  _Check_return_opt_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _i64toa_s(
+    _In_ __int64 _Val,
+    _Out_writes_z_(_Size) char *_DstBuf,
+    _In_ size_t _Size,
+    _In_ int _Radix);
+
+  _Check_return_opt_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _ui64toa_s(
+    _In_ unsigned __int64 _Val,
+    _Out_writes_z_(_Size) char *_DstBuf,
+    _In_ size_t _Size,
+    _In_ int _Radix);
+
+  _Check_return_opt_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _ltoa_s(
+    _In_ long _Val,
+    _Out_writes_z_(_Size) char *_DstBuf,
+    _In_ size_t _Size,
+    _In_ int _Radix);
+
+  _Success_(return!=EINVAL)
+  _Check_return_opt_
+  _CRTIMP
+  errno_t
+  __cdecl
+  mbstowcs_s(
+    _Out_opt_ size_t *pcchConverted,
+    _Out_writes_to_opt_(sizeInWords, *pcchConverted) wchar_t *pwcstr,
+    _In_ size_t sizeInWords,
+    _In_reads_or_z_(count) const char *pmbstr,
+    _In_ size_t count);
+
+  _Check_return_opt_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _mbstowcs_s_l(
+    _Out_opt_ size_t *_PtNumOfCharConverted,
+    _Out_writes_to_opt_(_SizeInWords, *_PtNumOfCharConverted) wchar_t *_DstBuf,
+    _In_ size_t _SizeInWords,
+    _In_reads_or_z_(_MaxCount) const char *_SrcBuf,
+    _In_ size_t _MaxCount,
+    _In_opt_ _locale_t _Locale);
+
+  _Check_return_opt_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _ultoa_s(
+    _In_ unsigned long _Val,
+    _Out_writes_z_(_Size) char *_DstBuf,
+    _In_ size_t _Size,
+    _In_ int _Radix);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _wctomb_s_l(
+    _Out_opt_ int *_SizeConverted,
+    _Out_writes_opt_z_(_SizeInBytes) char *_MbCh,
+    _In_ size_t _SizeInBytes,
+    _In_ wchar_t _WCh,
+    _In_opt_ _locale_t _Locale);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  wcstombs_s(
+    _Out_opt_ size_t *_PtNumOfCharConverted,
+    _Out_writes_bytes_to_opt_(_DstSizeInBytes, *_PtNumOfCharConverted) char *_Dst,
+    _In_ size_t _DstSizeInBytes,
+    _In_z_ const wchar_t *_Src,
+    _In_ size_t _MaxCountInBytes);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _wcstombs_s_l(
+    _Out_opt_ size_t *_PtNumOfCharConverted,
+    _Out_writes_bytes_to_opt_(_DstSizeInBytes, *_PtNumOfCharConverted) char *_Dst,
+    _In_ size_t _DstSizeInBytes,
+    _In_z_ const wchar_t *_Src,
+    _In_ size_t _MaxCountInBytes,
+    _In_opt_ _locale_t _Locale);

#ifndef _WSTDLIB_S_DEFINED
 #define _WSTDLIB_S_DEFINED
-  _CRTIMP errno_t __cdecl _itow_s (int _Val,wchar_t *_DstBuf,size_t _SizeInWords,int _Radix);
-  _CRTIMP errno_t __cdecl _ltow_s (long _Val,wchar_t *_DstBuf,size_t _SizeInWords,int _Radix);
-  _CRTIMP errno_t __cdecl _ultow_s (unsigned long _Val,wchar_t *_DstBuf,size_t _SizeInWords,int _Radix);
-  _CRTIMP errno_t __cdecl _wgetenv_s(size_t *_ReturnSize,wchar_t *_DstBuf,size_t _DstSizeInWords,const wchar_t *_VarName);
-  _CRTIMP errno_t __cdecl _wdupenv_s(wchar_t **_Buffer,size_t *_BufferSizeInWords,const wchar_t *_VarName);
-  _CRTIMP errno_t __cdecl _i64tow_s(__int64 _Val,wchar_t *_DstBuf,size_t _SizeInWords,int _Radix);
-  _CRTIMP errno_t __cdecl _ui64tow_s(unsigned __int64 _Val,wchar_t *_DstBuf,size_t _SizeInWords,int _Radix);
-#endif
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _itow_s(
+    _In_ int _Val,
+    _Out_writes_z_(_SizeInWords) wchar_t *_DstBuf,
+    _In_ size_t _SizeInWords,
+    _In_ int _Radix);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _ltow_s(
+    _In_ long _Val,
+    _Out_writes_z_(_SizeInWords) wchar_t *_DstBuf,
+    _In_ size_t _SizeInWords,
+    _In_ int _Radix);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _ultow_s(
+    _In_ unsigned long _Val,
+    _Out_writes_z_(_SizeInWords) wchar_t *_DstBuf,
+    _In_ size_t _SizeInWords,
+    _In_ int _Radix);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _wgetenv_s(
+    _Out_ size_t *_ReturnSize,
+    _Out_writes_opt_z_(_DstSizeInWords) wchar_t *_DstBuf,
+    _In_ size_t _DstSizeInWords,
+    _In_z_ const wchar_t *_VarName);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _wdupenv_s(
+    _Outptr_result_buffer_maybenull_(*_BufferSizeInWords) _Outptr_result_z_ wchar_t **_Buffer,
+    _Out_opt_ size_t *_BufferSizeInWords,
+    _In_z_ const wchar_t *_VarName);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _i64tow_s(
+    _In_ __int64 _Val,
+    _Out_writes_z_(_SizeInWords) wchar_t *_DstBuf,
+    _In_ size_t _SizeInWords,
+    _In_ int _Radix);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _ui64tow_s(
+    _In_ unsigned __int64 _Val,
+    _Out_writes_z_(_SizeInWords) wchar_t *_DstBuf,
+    _In_ size_t _SizeInWords,
+    _In_ int _Radix);
+
+#endif /* _WSTDLIB_S_DEFINED */

#ifndef _POSIX_
-  _CRTIMP errno_t __cdecl _ecvt_s(char *_DstBuf,size_t _Size,double _Val,int _NumOfDights,int *_PtDec,int *_PtSign);
-  _CRTIMP errno_t __cdecl _fcvt_s(char *_DstBuf,size_t _Size,double _Val,int _NumOfDec,int *_PtDec,int *_PtSign);
-  _CRTIMP errno_t __cdecl _gcvt_s(char *_DstBuf,size_t _Size,double _Val,int _NumOfDigits);
-  _CRTIMP errno_t __cdecl _makepath_s(char *_PathResult,size_t _Size,const char *_Drive,const char *_Dir,const char *_Filename,const char *_Ext);
-  _CRTIMP errno_t __cdecl _putenv_s(const char *_Name,const char *_Value);
-  _CRTIMP errno_t __cdecl _searchenv_s(const char *_Filename,const char *_EnvVar,char *_ResultPath,size_t _SizeInBytes);
-  _CRTIMP errno_t __cdecl _splitpath_s(const char *_FullPath,char *_Drive,size_t _DriveSize,char *_Dir,size_t _DirSize,char *_Filename,size_t _FilenameSize,char *_Ext,size_t _ExtSize);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _ecvt_s(
+    _Out_writes_z_(_Size) char *_DstBuf,
+    _In_ size_t _Size,
+    _In_ double _Val,
+    _In_ int _NumOfDights,
+    _Out_ int *_PtDec,
+    _Out_ int *_PtSign);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _fcvt_s(
+    _Out_writes_z_(_Size) char *_DstBuf,
+    _In_ size_t _Size,
+    _In_ double _Val,
+    _In_ int _NumOfDec,
+    _Out_ int *_PtDec,
+    _Out_ int *_PtSign);
+
+  _CRTIMP
+  errno_t
+  __cdecl
+  _gcvt_s(
+    _Out_writes_z_(_Size) char *_DstBuf,
+    _In_ size_t _Size,
+    _In_ double _Val,
+    _In_ int _NumOfDigits);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _makepath_s(
+    _Out_writes_z_(_Size) char *_PathResult,
+    _In_ size_t _Size,
+    _In_opt_z_ const char *_Drive,
+    _In_opt_z_ const char *_Dir,
+    _In_opt_z_ const char *_Filename,
+    _In_opt_z_ const char *_Ext);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _putenv_s(
+    _In_z_ const char *_Name,
+    _In_z_ const char *_Value);
+
+  _CRTIMP
+  errno_t
+  __cdecl
+  _searchenv_s(
+    _In_z_ const char *_Filename,
+    _In_z_ const char *_EnvVar,
+    _Out_writes_z_(_SizeInBytes) char *_ResultPath,
+    _In_ size_t _SizeInBytes);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _splitpath_s(
+    _In_z_ const char *_FullPath,
+    _Out_writes_opt_z_(_DriveSize) char *_Drive,
+    _In_ size_t _DriveSize,
+    _Out_writes_opt_z_(_DirSize) char *_Dir,
+    _In_ size_t _DirSize,
+    _Out_writes_opt_z_(_FilenameSize) char *_Filename,
+    _In_ size_t _FilenameSize,
+    _Out_writes_opt_z_(_ExtSize) char *_Ext,
+    _In_ size_t _ExtSize);

#ifndef _WSTDLIBP_S_DEFINED
 #define _WSTDLIBP_S_DEFINED
-  _CRTIMP errno_t __cdecl _wmakepath_s(wchar_t *_PathResult,size_t _SizeInWords,const wchar_t *_Drive,const wchar_t *_Dir,const wchar_t *_Filename,const wchar_t *_Ext);
-  _CRTIMP errno_t __cdecl _wputenv_s(const wchar_t *_Name,const wchar_t *_Value);
-  _CRTIMP errno_t __cdecl _wsearchenv_s(const wchar_t *_Filename,const wchar_t *_EnvVar,wchar_t *_ResultPath,size_t _SizeInWords);
-  _CRTIMP errno_t __cdecl _wsplitpath_s(const wchar_t *_FullPath,wchar_t *_Drive,size_t _DriveSizeInWords,wchar_t *_Dir,size_t _DirSizeInWords,wchar_t *_Filename,size_t _FilenameSizeInWords,wchar_t *_Ext,size_t _ExtSizeInWords);
-#endif
-#endif
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _wmakepath_s(
+    _Out_writes_z_(_SizeInWords) wchar_t *_PathResult,
+    _In_ size_t _SizeInWords,
+    _In_opt_z_ const wchar_t *_Drive,
+    _In_opt_z_ const wchar_t *_Dir,
+    _In_opt_z_ const wchar_t *_Filename,
+    _In_opt_z_ const wchar_t *_Ext);
+
+  _Check_return_wat_
+  _CRTIMP
+  errno_t
+  __cdecl
+  _wputenv_s(
+    _In_z_ const wchar_t *_Name,
+    _In_z_ const wchar_t *_Value);
+
+  _CRTIMP
+  errno_t
+  __cdecl
+  _wsearchenv_s(
+    _In_z_ const wchar_t *_Filename,
+    _In_z_ const wchar_t *_EnvVar,
+    _Out_writes_z_(_SizeInWords) wchar_t *_ResultPath,
+    _In_ size_t _SizeInWords);
+
+  _CRTIMP
+  errno_t
+  __cdecl
+  _wsplitpath_s(
+    _In_z_ const wchar_t *_FullPath,
+    _Out_writes_opt_z_(_DriveSizeInWords) wchar_t *_Drive,
+    _In_ size_t _DriveSizeInWords,
+    _Out_writes_opt_z_(_DirSizeInWords) wchar_t *_Dir,
+    _In_ size_t _DirSizeInWords,
+    _Out_writes_opt_z_(_FilenameSizeInWords) wchar_t *_Filename,
+    _In_ size_t _FilenameSizeInWords,
+    _Out_writes_opt_z_(_ExtSizeInWords) wchar_t *_Ext,
+    _In_ size_t _ExtSizeInWords);
+
+#endif /* _WSTDLIBP_S_DEFINED */
+
+#endif /* _POSIX_ */

#ifdef __cplusplus
 }
 #endif

-#endif
-#endif
+#endif /* defined(MINGW_HAS_SECURE_API) */
+
+#endif /* _INC_STDLIB_S */

Modified: trunk/reactos/include/crt/stdlib.h
URL: http://svn.reactos.org/svn/reactos/trunk/reactos/include/crt/stdlib.h?rev=58...
==============================================================================
--- trunk/reactos/include/crt/stdlib.h [iso-8859-1] (original)
+++ trunk/reactos/include/crt/stdlib.h [iso-8859-1] Fri Mar 15 22:04:05 2013
@@ -131,11 +131,11 @@

typedef void (__cdecl *_purecall_handler)(void);

-  _CRTIMP _purecall_handler __cdecl _set_purecall_handler(_purecall_handler _Handler);
+  _CRTIMP _purecall_handler __cdecl _set_purecall_handler(_In_opt_ _purecall_handler _Handler);
   _CRTIMP _purecall_handler __cdecl _get_purecall_handler(void);

typedef void (__cdecl *_invalid_parameter_handler)(const wchar_t *,const wchar_t *,const wchar_t *,unsigned int,uintptr_t);
-  _invalid_parameter_handler __cdecl _set_invalid_parameter_handler(_invalid_parameter_handler _Handler);
+  _invalid_parameter_handler __cdecl _set_invalid_parameter_handler(_In_opt_ _invalid_parameter_handler _Handler);
   _invalid_parameter_handler __cdecl _get_invalid_parameter_handler(void);

#include <errno.h>
@@ -186,8 +186,8 @@

_CRTIMP errno_t __cdecl _get_environ(_Out_ char***);
   _CRTIMP errno_t __cdecl _get_wenviron(_Out_ wchar_t***);
-  _CRTIMP errno_t __cdecl _get_pgmptr(_Deref_out_z_ char **_Value);
-  _CRTIMP errno_t __cdecl _get_wpgmptr(_Deref_out_z_ wchar_t **_Value);
+  _CRTIMP errno_t __cdecl _get_pgmptr(_Outptr_result_z_ char **_Value);
+  _CRTIMP errno_t __cdecl _get_wpgmptr(_Outptr_result_z_ wchar_t **_Value);

#ifdef _M_CEE_PURE
   _CRTIMP int* __cdecl __p__fmode();
@@ -330,7 +330,7 @@
   void
   __cdecl
   qsort(
-    _Inout_updates_bytes_(_NumOfElements * _SizeOfElements) void *_Base,
+    _Inout_updates_bytes_(_NumOfElements * _SizeOfElements) _Post_readable_byte_size_(_NumOfElements * _SizeOfElements) void *_Base,
     _In_ size_t _NumOfElements,
     _In_ size_t _SizeOfElements,
     _In_ int (__cdecl *_PtFuncCompare)(const void *,const void *));
@@ -464,6 +464,7 @@

#endif /* _INTEGRAL_MAX_BITS >= 64 */

+  _Check_return_
   ldiv_t
   __cdecl
   ldiv(
@@ -710,6 +711,7 @@
   malloc(
     _In_ size_t _Size);

+  _Success_(return != 0)
   _Check_return_
   _Ret_maybenull_
   _Post_writable_byte_size_(_NewSize)
@@ -719,6 +721,7 @@
     _Pre_maybenull_ _Post_invalid_ void *_Memory,
     _In_ size_t _NewSize);

+  _Success_(return != 0)
   _Check_return_
   _Ret_maybenull_
   _Post_writable_byte_size_(_Count * _Size)
@@ -768,6 +771,7 @@
     _In_ size_t _Alignment,
     _In_ size_t _Offset);

+  _Success_(return != 0)
   _Check_return_
   _Ret_maybenull_
   _Post_writable_byte_size_(_Size)
@@ -779,6 +783,7 @@
     _In_ size_t _Size,
     _In_ size_t _Alignment);

+  _Success_(return != 0)
   _Check_return_
   _Ret_maybenull_
   _Post_writable_byte_size_(_Count * _Size)
@@ -791,6 +796,7 @@
     _In_ size_t _Size,
     _In_ size_t _Alignment);

+  _Success_(return != 0)
   _Check_return_
   _Ret_maybenull_
   _Post_writable_byte_size_(_Size)
@@ -1143,12 +1149,14 @@
     _In_z_ char *_Str,
     _In_opt_ _locale_t _Locale);

+  _Check_return_
   unsigned long
   __cdecl
   _lrotl(
     _In_ unsigned long _Val,
     _In_ int _Shift);

+  _Check_return_
   unsigned long
   __cdecl
   _lrotr(
@@ -1426,10 +1434,10 @@

__MINGW_EXTENSION typedef struct { long long quot, rem; } lldiv_t;

-  __MINGW_EXTENSION lldiv_t __cdecl lldiv(long long, long long);
+  _Check_return_ __MINGW_EXTENSION lldiv_t __cdecl lldiv(_In_ long long, _In_ long long);

#ifndef _MSC_VER
-  __MINGW_EXTENSION __CRT_INLINE long long __cdecl llabs(long long _j) { return (_j >= 0 ? _j : -_j); }
+  __MINGW_EXTENSION __CRT_INLINE long long __cdecl llabs(_In_ long long _j) { return (_j >= 0 ? _j : -_j); }
 #endif

__MINGW_EXTENSION long long  __cdecl strtoll(const char* __restrict__, char** __restrict, int);