Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/crt_abstraction_requirements.md

raw
1 CRTAbstractions Requirements
2 ================
3
4 ## Overview
5
6 Many old CRT functions have newer, more secure versions via Microsoft's implementation of the run-time library. These have the _s ("secure") suffix.
7 The CRTAbstractions module provides the same secure functions for when not using a Microsoft platforms.
8
9 ## Generic Requirements
10
11 **SRS_CRT_ABSTRACTIONS_99_001: [** The module shall not redefine the secure functions implemented by Microsoft CRT. **]**
12
13 **SRS_CRT_ABSTRACTIONS_99_040: [** The module shall still compile when building on a Microsoft platform. **]**
14
15 ##Exposed API
16 **SRS_CRT_ABSTRACTIONS_99_002: [**
17 CRTAbstractions module shall expose the following API:
18 ```c
19 int strcat_s(char* dst, size_t dstSizeInBytes, const char* src);
20 int strcpy_s(char* dst, size_t dstSizeInBytes, const char* src);
21 int strncpy_s(char* dst, size_t dstSizeInBytes, const char* src, size_t maxCount);
22 int sprintf_s(char* dst, size_t dstSizeInBytes, const char* format, ... );
23 int mallocAndStrcpy_s(char** destination, const char* source);
24 int unsignedIntToString(char* destination, size_t destinationSize, unsigned int value);
25 int size_tToString(char* destination, size_t destinationSize, size_t value);
26 ```
27 **]**
28
29 ### strcat_s
30 ```c
31 int strcat_s(char* dst, size_t dstSizeInBytes, const char* src);
32 ```
33
34 **SRS_CRT_ABSTRACTIONS_99_008: [** strcat_s shall append the src to dst and terminates the resulting string with a null character. **]**
35
36 **SRS_CRT_ABSTRACTIONS_99_009: [** The initial character of src shall overwrite the terminating null character of dst. **]**
37
38 **SRS_CRT_ABSTRACTIONS_99_003: [** strcat_s shall return Zero upon success. **]**
39
40 strcat_s shall return an error code upon failure as follows:
41
42 **SRS_CRT_ABSTRACTIONS_99_004: [** If dst is NULL or unterminated, the error code returned shall be EINVAL & dst shall not be modified. **]**
43
44 **SRS_CRT_ABSTRACTIONS_99_005: [** If src is NULL, the error code returned shall be EINVAL and dst[0 **]** shall be set to 0.]
45 **SRS_CRT_ABSTRACTIONS_99_006: [** If the dstSizeInBytes is 0 or smaller than the required size for dst & src, the error code returned shall be ERANGE & dst[0 **]** set to 0.]
46
47 ### strcpy_s
48 ```c
49 int strcpy_s(char* dst, size_t dstSizeInBytes, const char* src);
50 ```
51 **SRS_CRT_ABSTRACTIONS_99_016: [** strcpy_s shall copy the contents in the address of src, including the terminating null character, to the location that's specified by dst. **]**
52
53 **SRS_CRT_ABSTRACTIONS_99_011: [** strcpy_s shall return Zero upon success **]**
54
55 strcpy shall return an error code upon failure as follows:
56
57 **SRS_CRT_ABSTRACTIONS_99_012: [** If dst is NULL, the error code returned shall be EINVAL & dst shall not be modified. **]**
58
59 **SRS_CRT_ABSTRACTIONS_99_013: [** If src is NULL, the error code returned shall be EINVAL and dst[0 **]** shall be set to 0.]
60 **SRS_CRT_ABSTRACTIONS_99_014: [** If the dstSizeInBytes is 0 or smaller than the required size for the src string, the error code returned shall be ERANGE & dst[0 **]** set to 0.]
61
62 ### strncpy_s
63 ```c
64 int strncpy_s(char* dst, size_t dstSizeInBytes, const char* src, size_t maxCount);
65 ```
66 **SRS_CRT_ABSTRACTIONS_99_025: [** strncpy_s shall copy the first N characters of src to dst, where N is the lesser of MaxCount and the length of src. **]**
67
68 **SRS_CRT_ABSTRACTIONS_99_041: [** If those N characters will fit within dst (whose size is given as dstSizeInBytes) and still leave room for a null terminator, then those characters shall be copied and a terminating null is appended; otherwise, strDest[0 **]** is set to the null character and ERANGE error code returned.]
69
70 **SRS_CRT_ABSTRACTIONS_99_026: [** If MaxCount is _TRUNCATE (defined as -1), then as much of src as will fit into dst shall be copied while still leaving room for the terminating null to be appended. **]**
71
72 **SRS_CRT_ABSTRACTIONS_99_018: [** strncpy_s shall return Zero upon success **]**
73
74 strncpy_s shall return an error code upon failure as follows:
75
76 **SRS_CRT_ABSTRACTIONS_99_019: [** If truncation occurred as a result of the copy, the error code returned shall be STRUNCATE. **]**
77
78 **SRS_CRT_ABSTRACTIONS_99_020: [** If dst is NULL, the error code returned shall be EINVAL and dst shall not be modified. **]**
79
80 **SRS_CRT_ABSTRACTIONS_99_021: [** If src is NULL, the error code returned shall be EINVAL and dst[0 **]** shall be set to 0.]
81
82 **SRS_CRT_ABSTRACTIONS_99_022: [** If the dstSizeInBytes is 0, the error code returned shall be EINVAL and dst shall not be modified. **]**
83
84 **SRS_CRT_ABSTRACTIONS_99_023: [** If dst is not NULL & dstSizeInBytes is smaller than the required size for the src string, the error code returned shall be ERANGE and dst[0 **]** shall be set to 0.]
85
86 ### sprintf_s
87 ```c
88 int sprintf_s(char* dst, size_t dstSizeInBytes, const char* format, ... );
89 ```
90
91 **SRS_CRT_ABSTRACTIONS_99_029: [** The sprintf_s function shall format and store series of characters and values in dst. Each argument (if any) is converted and output according to the corresponding Format Specification in the format variable. **]**
92
93 **SRS_CRT_ABSTRACTIONS_99_031: [** A null character is appended after the last character written. **]**
94
95 **SRS_CRT_ABSTRACTIONS_99_027: [** sprintf_s shall return the number of characters stored in dst upon success. This number shall not include the terminating null character. **]**
96
97 **SRS_CRT_ABSTRACTIONS_99_028: [** If dst or format is a null pointer, sprintf_s shall return -1 and set errno to EINVAL **]**
98
99 **SRS_CRT_ABSTRACTIONS_99_034: [** If the dst buffer is too small for the text being printed, then dst is set to an empty string and the function shall return -1. **]**
100
101 ### mallocAndStrcpy_s
102 ```c
103 int mallocAndStrcpy_s(char** destination, const char* source);
104 ```
105 **SRS_CRT_ABSTRACTIONS_99_038: [** mallocAndstrcpy_s shall allocate memory for destination buffer to fit the string in the source parameter. **]**
106
107 **SRS_CRT_ABSTRACTIONS_99_039: [** mallocAndstrcpy_s shall copy the contents in the address source, including the terminating null character into location specified by the destination pointer after the memory allocation. **]**
108
109 **SRS_CRT_ABSTRACTIONS_99_035: [** mallocAndstrcpy_s shall return Zero upon success **]**
110
111 mallocAndstrcpy_s shall return an error code upon failure as follows:
112
113 **SRS_CRT_ABSTRACTIONS_99_036: [** destination parameter or source parameter is NULL, the error code returned shall be EINVAL and destination shall not be modified. **]**
114
115 **SRS_CRT_ABSTRACTIONS_99_037: [** Upon failure to allocate memory for the destination, the function will return ENOMEM. **]**
116
117 ### unsignedIntToString
118 ```c
119 int unsignedIntToString(char* destination, size_t destinationSize, unsigned int value)
120 ```
121
122 **SRS_CRT_ABSTRACTIONS_02_001: [** unsignedIntToString shall convert the parameter value to its decimal representation as a string in the buffer indicated by parameter destination having the size indicated by parameter destinationSize. **]**
123
124 **SRS_CRT_ABSTRACTIONS_02_002: [** If the conversion fails for any reason (for example, insufficient buffer space), a non-zero return value shall be supplied and unsignedIntToString shall fail. **]**
125
126 **SRS_CRT_ABSTRACTIONS_02_003: [** If destination is NULL then unsignedIntToString shall fail. **]**
127
128 **SRS_CRT_ABSTRACTIONS_02_004: [** If the conversion has been successfull then unsignedIntToString shall return 0. **]**
129
130 ### size_tToString
131 ```c
132 int size_tToString(char* destination, size_t destinationSize, size_t value)
133 ```
134
135 **SRS_CRT_ABSTRACTIONS_02_001: [** size_tToString shall convert the parameter value to its decimal representation as a string in the buffer indicated by parameter destination having the size indicated by parameter destinationSize. **]**
136
137 **SRS_CRT_ABSTRACTIONS_02_002: [** If the conversion fails for any reason (for example, insufficient buffer space), a non-zero return value shall be supplied and size_tToString shall fail. **]**
138
139 **SRS_CRT_ABSTRACTIONS_02_003: [** If destination is NULL then size_tToString shall fail. **]**
140
141 **SRS_CRT_ABSTRACTIONS_02_004: [** If the conversion has been successfull then size_tToString shall return 0. **]**
142
143 ### strtoull_s
144 ```c
145 unsigned long long strtoull_s(const char* nptr, char** endptr, int base)
146 ```
147
148 **SRS_CRT_ABSTRACTIONS_21_001: [** The strtoull_s must convert the initial portion of the string pointed to by nptr to unsigned long long int representation. **]**
149
150 **SRS_CRT_ABSTRACTIONS_21_002: [** The strtoull_s must resembling an integer represented in some radix determined by the value of base. **]**
151
152 **SRS_CRT_ABSTRACTIONS_21_003: [** The strtoull_s must return the integer that represents the value in the initial part of the string. If any. **]**
153
154 **SRS_CRT_ABSTRACTIONS_21_004: [** The strtoull_s must return in endptr a final string of one or more unrecognized characters, including the terminating null character of the input string. **]**
155
156 **SRS_CRT_ABSTRACTIONS_21_005: [** The strtoull_s must convert number using base 2 to 36. **]**
157
158 **SRS_CRT_ABSTRACTIONS_21_006: [** The strtoull_s must use the letters from a (or A) through z (or Z) to represent the numbers between 10 to 35. **]**
159
160 **SRS_CRT_ABSTRACTIONS_21_007: [** If the base is 0 and no special chars precedes the number, strtoull_s must convert to a decimal (base 10). **]**
161
162 **SRS_CRT_ABSTRACTIONS_21_008: [** If the base is 0 and '0x' or '0X' precedes the number, strtoull_s must convert to a hexadecimal (base 16). **]**
163
164 **SRS_CRT_ABSTRACTIONS_21_009: [** If the base is 0 and '0' precedes the number, strtoull_s must convert to an octal (base 8). **]**
165
166 **SRS_CRT_ABSTRACTIONS_21_010: [** The white-space must be one of the characters ' ', '\f', '\n', '\r', '\t', '\v'. **]**
167
168 **SRS_CRT_ABSTRACTIONS_21_011: [** The valid sequence starts after the first non-white-space character, followed by an optional positive or negative sign, a number or a letter (depending of the base). **]**
169
170 **SRS_CRT_ABSTRACTIONS_21_012: [** If the subject sequence is empty or does not have the expected form, the strtoull_s must **not** perform any conversion and must returns 0L; the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer. **]**
171
172 **SRS_CRT_ABSTRACTIONS_21_013: [** If no conversion could be performed, the strtoull_s returns the value 0L. **]**
173
174 **SRS_CRT_ABSTRACTIONS_21_014: [** If the correct value is outside the range, the strtoull_s returns the value ULLONG_MAX, and errno will receive the value ERANGE. **]**
175
176 **SRS_CRT_ABSTRACTIONS_21_035: [** If the nptr is NULL, the strtoull_s must **not** perform any conversion and must returns 0L; endptr must receive NULL, provided that endptr is not a NULL pointer. **]**
177
178 **SRS_CRT_ABSTRACTIONS_21_038: [** If the subject sequence starts with a negative sign, the strtoull_s will convert it to the posive representation of the negative value. **]**
179
180 ### strtof_s
181 ```c
182 float strtof_s(const char* nptr, char** endptr)
183 ```
184
185 **SRS_CRT_ABSTRACTIONS_21_015: [** The strtof_s must convert the initial portion of the string pointed to by nptr to float representation. **]**
186
187 **SRS_CRT_ABSTRACTIONS_21_016: [** The strtof_s must return the float that represents the value in the initial part of the string. If any. **]**
188
189 **SRS_CRT_ABSTRACTIONS_21_017: [** The strtof_s must return in endptr a final string of one or more unrecognized characters, including the terminating null character of the input string. **]**
190
191 **SRS_CRT_ABSTRACTIONS_21_018: [** The white-space for strtof_s must be one of the characters ' ', '\f', '\n', '\r', '\t', '\v'. **]**
192
193 **SRS_CRT_ABSTRACTIONS_21_019: [** The valid sequence for strtof_s starts after the first non-white-space character, followed by an optional positive or negative sign, a number, 'INF', or 'NAN' (ignoring case). **]**
194
195 **SRS_CRT_ABSTRACTIONS_21_020: [** If the subject sequence is empty or does not have the expected form, the strtof_s must **not** perform any conversion and must returns 0.0f; the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer. **]**
196
197 **SRS_CRT_ABSTRACTIONS_21_021: [** If no conversion could be performed, the strtof_s returns the value 0.0f. **]**
198
199 **SRS_CRT_ABSTRACTIONS_21_022: [** If the correct value is outside the range, the strtof_s returns the value plus or minus HUGE_VALF, and errno will receive the value ERANGE. **]**
200
201 **SRS_CRT_ABSTRACTIONS_21_023: [** If the string is 'INF' of 'INFINITY' (ignoring case), the strtof_s must return the INFINITY value for float. **]**
202
203 **SRS_CRT_ABSTRACTIONS_21_024: [** If the string is 'NAN' or 'NAN(...)' (ignoring case), the strtof_s must return 0.0f and points endptr to the first character after the 'NAN' sequence. **]**
204
205 **SRS_CRT_ABSTRACTIONS_21_036: [** If the nptr is NULL, the strtof_s must **not** perform any conversion and must returns 0.0f; endptr must receive NULL, provided that endptr is not a NULL pointer. **]**
206
207 ### strtold_s
208 ```c
209 long double strtold_s(const char* nptr, char** endptr)
210 ```
211
212 **SRS_CRT_ABSTRACTIONS_21_025: [** The strtold_s must convert the initial portion of the string pointed to by nptr to long double representation. **]**
213
214 **SRS_CRT_ABSTRACTIONS_21_026: [** The strtold_s must return the long double that represents the value in the initial part of the string. If any. **]**
215
216 **SRS_CRT_ABSTRACTIONS_21_027: [** The strtold_s must return in endptr a final string of one or more unrecognized characters, including the terminating null character of the input string. **]**
217
218 **SRS_CRT_ABSTRACTIONS_21_028: [** The white-space for strtold_s must be one of the characters ' ', '\f', '\n', '\r', '\t', '\v'. **]**
219
220 **SRS_CRT_ABSTRACTIONS_21_029: [** The valid sequence for strtold_s starts after the first non-white-space character, followed by an optional positive or negative sign, a number, 'INF', or 'NAN' (ignoring case). **]**
221
222 **SRS_CRT_ABSTRACTIONS_21_030: [** If the subject sequence is empty or does not have the expected form, the strtold_s must **not** perform any conversion and must returns 0.0; the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a NULL pointer. **]**
223
224 **SRS_CRT_ABSTRACTIONS_21_031: [** If no conversion could be performed, the strtold_s returns the value 0.0. **]**
225
226 **SRS_CRT_ABSTRACTIONS_21_032: [** If the correct value is outside the range, the strtold_s returns the value plus or minus HUGE_VALL, and errno will receive the value ERANGE. **]**
227
228 **SRS_CRT_ABSTRACTIONS_21_033: [** If the string is 'INF' of 'INFINITY' (ignoring case), the strtold_s must return the INFINITY value for long double. **]**
229
230 **SRS_CRT_ABSTRACTIONS_21_034: [** If the string is 'NAN' or 'NAN(...)' (ignoring case), the strtold_s must return 0.0 and points endptr to the first character after the 'NAN' sequence. **]**
231
232 **SRS_CRT_ABSTRACTIONS_21_037: [** If the nptr is NULL, the strtold_s must **not** perform any conversion and must returns 0.0; endptr must receive NULL, provided that endptr is not a NULL pointer. **]**