]>
Commit | Line | Data |
---|---|---|
2aa62f2b | 1 | /** @file\r |
2 | The header <string.h> declares one type and several functions, and defines\r | |
3 | one macro useful for manipulating arrays of character type and other objects\r | |
4 | treated as arrays of character type. Various methods are used for\r | |
5 | determining the lengths of the arrays, but in all cases a char * or void *\r | |
6 | argument points to the initial (lowest addressed) character of the array. If\r | |
7 | an array is accessed beyond the end of an object, the behavior is undefined.\r | |
8 | \r | |
9 | Where an argument declared as size_t n specifies the length of the array for\r | |
10 | a function, n can have the value zero on a call to that function. Unless\r | |
11 | explicitly stated otherwise in the description of those functions, pointer\r | |
12 | arguments on such a call shall still have valid values.\r | |
13 | \r | |
14 | For all functions declared in this header, each character shall be\r | |
15 | interpreted as if it had the type unsigned char (and therefore every possible\r | |
16 | object representation is valid and has a different value).\r | |
17 | \r | |
53e1e5c6 | 18 | Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>\r |
2aa62f2b | 19 | This program and the accompanying materials are licensed and made available under\r |
20 | the terms and conditions of the BSD License that accompanies this distribution.\r | |
21 | The full text of the license may be found at\r | |
22 | http://opensource.org/licenses/bsd-license.php.\r | |
23 | \r | |
24 | THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r | |
25 | WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r | |
26 | \r | |
27 | **/\r | |
28 | #ifndef _STRING_H\r | |
29 | #define _STRING_H\r | |
30 | #include <sys/EfiCdefs.h>\r | |
31 | \r | |
32 | #ifdef _EFI_SIZE_T_\r | |
33 | typedef _EFI_SIZE_T_ size_t;\r | |
34 | #undef _EFI_SIZE_T_\r | |
35 | #undef _BSD_SIZE_T_\r | |
36 | #endif\r | |
37 | \r | |
38 | __BEGIN_DECLS\r | |
39 | \r | |
40 | /* ################ Copying Functions ################################# */\r | |
41 | \r | |
42 | /** The memcpy function copies n characters from the object pointed to by s2\r | |
43 | into the object pointed to by s1. If copying takes place between objects\r | |
44 | that overlap, the behavior is undefined.\r | |
45 | \r | |
46 | @return The memcpy function returns the value of s1.\r | |
47 | **/\r | |
48 | void *memcpy(void * __restrict s1, const void * __restrict s2, size_t n);\r | |
49 | \r | |
50 | /** The memmove function copies n characters from the object pointed to by s2\r | |
51 | into the object pointed to by s1. Copying takes place as if the n\r | |
52 | characters from the object pointed to by s2 are first copied into a\r | |
53 | temporary array of n characters that does not overlap the objects pointed\r | |
54 | to by s1 and s2, and then the n characters from the temporary array are\r | |
55 | copied into the object pointed to by s1.\r | |
56 | \r | |
57 | @return The memmove function returns the value of s1.\r | |
58 | **/\r | |
59 | void *memmove(void *s1, const void *s2, size_t n);\r | |
60 | \r | |
61 | /** The strcpy function copies the string pointed to by s2 (including the\r | |
62 | terminating null character) into the array pointed to by s1. If copying\r | |
63 | takes place between objects that overlap, the behavior is undefined.\r | |
64 | \r | |
65 | @return The strcpy function returns the value of s1.\r | |
66 | **/\r | |
67 | char *strcpy(char * __restrict s1, const char * __restrict s2);\r | |
68 | \r | |
69 | /** The strncpy function copies not more than n characters (characters that\r | |
70 | follow a null character are not copied) from the array pointed to by s2 to\r | |
71 | the array pointed to by s1. If copying takes place between objects that\r | |
72 | overlap, the behavior is undefined.\r | |
73 | \r | |
74 | If the array pointed to by s2 is a string that is shorter than n\r | |
75 | characters, null characters are appended to the copy in the array pointed\r | |
76 | to by s1, until n characters in all have been written.\r | |
77 | \r | |
78 | @return The strncpy function returns the value of s1.\r | |
79 | **/\r | |
80 | char *strncpy(char * __restrict s1, const char * __restrict s2, size_t n);\r | |
81 | \r | |
82 | /** The strncpyX function copies not more than n-1 characters (characters that\r | |
83 | follow a null character are not copied) from the array pointed to by s2 to\r | |
84 | the array pointed to by s1. Array s1 is guaranteed to be NULL terminated.\r | |
85 | If copying takes place between objects that overlap,\r | |
86 | the behavior is undefined.\r | |
87 | \r | |
88 | strncpyX exists because normal strncpy does not indicate if the copy was\r | |
89 | terminated because of exhausting the buffer or reaching the end of s2.\r | |
90 | \r | |
91 | @return The strncpyX function returns 0 if the copy operation was\r | |
92 | terminated because it reached the end of s1. Otherwise,\r | |
93 | a non-zero value is returned indicating how many characters\r | |
94 | remain in s1.\r | |
95 | **/\r | |
96 | int strncpyX(char * __restrict s1, const char * __restrict s2, size_t n);\r | |
97 | \r | |
98 | /* ################ Concatenation Functions ########################### */\r | |
99 | \r | |
100 | /** The strcat function appends a copy of the string pointed to by s2\r | |
101 | (including the terminating null character) to the end of the string pointed\r | |
102 | to by s1. The initial character of s2 overwrites the null character at the\r | |
103 | end of s1. If copying takes place between objects that overlap, the\r | |
104 | behavior is undefined.\r | |
105 | \r | |
106 | @return The strcat function returns the value of s1.\r | |
107 | **/\r | |
108 | char *strcat(char * __restrict s1, const char * __restrict s2);\r | |
109 | \r | |
110 | /** The strncat function appends not more than n characters (a null character\r | |
111 | and characters that follow it are not appended) from the array pointed to\r | |
112 | by s2 to the end of the string pointed to by s1. The initial character of\r | |
113 | s2 overwrites the null character at the end of s1. A terminating null\r | |
114 | character is always appended to the result. If copying takes place\r | |
115 | between objects that overlap, the behavior is undefined.\r | |
116 | \r | |
117 | @return The strncat function returns the value of s1.\r | |
118 | **/\r | |
119 | char *strncat(char * __restrict s1, const char * __restrict s2, size_t n);\r | |
120 | \r | |
121 | /** The strncatX function appends not more than n characters (a null character\r | |
122 | and characters that follow it are not appended) from the array pointed to\r | |
123 | by s2 to the end of the string pointed to by s1. The initial character of\r | |
124 | s2 overwrites the null character at the end of s1. The result is always\r | |
125 | terminated with a null character. If copying takes place between objects\r | |
126 | that overlap, the behavior is undefined.\r | |
127 | \r | |
128 | strncatX exists because normal strncat does not indicate if the operation\r | |
129 | was terminated because of exhausting n or reaching the end of s2.\r | |
130 | \r | |
131 | @return The strncatX function returns 0 if the operation was terminated\r | |
132 | because it reached the end of s1. Otherwise, a non-zero value is\r | |
133 | returned indicating how many characters remain in s1.\r | |
134 | **/\r | |
135 | int strncatX(char * __restrict s1, const char * __restrict s2, size_t n);\r | |
136 | \r | |
137 | /* ################ Comparison Functions ############################## */\r | |
138 | \r | |
139 | /** The memcmp function compares the first n characters of the object pointed\r | |
140 | to by s1 to the first n characters of the object pointed to by s2.\r | |
141 | \r | |
142 | @return The memcmp function returns an integer greater than, equal to, or\r | |
143 | less than zero, accordingly as the object pointed to by s1 is\r | |
144 | greater than, equal to, or less than the object pointed to by s2.\r | |
145 | **/\r | |
146 | int memcmp(const void *s1, const void *s2, size_t n);\r | |
147 | \r | |
148 | /** The strcmp function compares the string pointed to by s1 to the string\r | |
149 | pointed to by s2.\r | |
150 | \r | |
151 | @return The strcmp function returns an integer greater than, equal to, or\r | |
152 | less than zero, accordingly as the string pointed to by s1 is\r | |
153 | greater than, equal to, or less than the string pointed to by s2.\r | |
154 | **/\r | |
155 | int strcmp(const char *s1, const char *s2);\r | |
156 | \r | |
157 | /** The strcoll function compares the string pointed to by s1 to the string\r | |
158 | pointed to by s2, both interpreted as appropriate to the LC_COLLATE\r | |
159 | category of the current locale.\r | |
160 | \r | |
161 | @return The strcoll function returns an integer greater than, equal to,\r | |
162 | or less than zero, accordingly as the string pointed to by s1 is\r | |
163 | greater than, equal to, or less than the string pointed to by s2\r | |
164 | when both are interpreted as appropriate to the current locale.\r | |
165 | **/\r | |
166 | int strcoll(const char *s1, const char *s2);\r | |
167 | \r | |
168 | /** The strncmp function compares not more than n characters (characters that\r | |
169 | follow a null character are not compared) from the array pointed to by s1\r | |
170 | to the array pointed to by s2.\r | |
171 | \r | |
172 | @return The strncmp function returns an integer greater than, equal to,\r | |
173 | or less than zero, accordingly as the possibly null-terminated\r | |
174 | array pointed to by s1 is greater than, equal to, or less than\r | |
175 | the possibly null-terminated array pointed to by s2.\r | |
176 | **/\r | |
177 | int strncmp(const char *s1, const char *s2, size_t n);\r | |
178 | \r | |
179 | /** The strxfrm function transforms the string pointed to by s2 and places the\r | |
180 | resulting string into the array pointed to by s1. The transformation is\r | |
181 | such that if the strcmp function is applied to two transformed strings, it\r | |
182 | returns a value greater than, equal to, or less than zero, corresponding to\r | |
183 | the result of the strcoll function applied to the same two original\r | |
184 | strings. No more than n characters are placed into the resulting array\r | |
185 | pointed to by s1, including the terminating null character. If n is zero,\r | |
186 | s1 is permitted to be a null pointer. If copying takes place between\r | |
187 | objects that overlap, the behavior is undefined.\r | |
188 | \r | |
189 | @return The strxfrm function returns the length of the transformed string\r | |
190 | (not including the terminating null character). If the value\r | |
191 | returned is n or more, the contents of the array pointed to by s1\r | |
192 | are indeterminate.\r | |
193 | **/\r | |
194 | size_t strxfrm(char * __restrict s1, const char * __restrict s2, size_t n);\r | |
195 | \r | |
196 | /* ################ Search Functions ################################## */\r | |
197 | \r | |
198 | /** The memchr function locates the first occurrence of c (converted to an\r | |
199 | unsigned char) in the initial n characters (each interpreted as\r | |
200 | unsigned char) of the object pointed to by s.\r | |
201 | \r | |
202 | @return The memchr function returns a pointer to the located character,\r | |
203 | or a null pointer if the character does not occur in the object.\r | |
204 | **/\r | |
205 | void *memchr(const void *s, int c, size_t n);\r | |
206 | \r | |
207 | /** The strchr function locates the first occurrence of c (converted to a char)\r | |
208 | in the string pointed to by s. The terminating null character is considered\r | |
209 | to be part of the string.\r | |
210 | \r | |
211 | @return The strchr function returns a pointer to the located character,\r | |
212 | or a null pointer if the character does not occur in the string.\r | |
213 | **/\r | |
214 | char *strchr(const char *s, int c);\r | |
215 | \r | |
216 | /** The strcspn function computes the length of the maximum initial segment of\r | |
217 | the string pointed to by s1 which consists entirely of characters NOT from\r | |
218 | the string pointed to by s2.\r | |
219 | \r | |
220 | @return The strcspn function returns the length of the segment.\r | |
221 | **/\r | |
222 | size_t strcspn(const char *s1, const char *s2);\r | |
223 | \r | |
224 | /** The strpbrk function locates the first occurrence in the string pointed to\r | |
225 | by s1 of any character from the string pointed to by s2.\r | |
226 | \r | |
227 | @return The strpbrk function returns a pointer to the character, or a\r | |
228 | null pointer if no character from s2 occurs in s1.\r | |
229 | **/\r | |
230 | char *strpbrk(const char *s1, const char *s2);\r | |
231 | \r | |
232 | /** The strrchr function locates the last occurrence of c (converted to a char)\r | |
233 | in the string pointed to by s. The terminating null character is considered\r | |
234 | to be part of the string.\r | |
235 | \r | |
236 | @return The strrchr function returns a pointer to the character, or a\r | |
237 | null pointer if c does not occur in the string.\r | |
238 | **/\r | |
239 | char *strrchr(const char *s, int c);\r | |
240 | \r | |
241 | /** The strspn function computes the length of the maximum initial segment of\r | |
242 | the string pointed to by s1 which consists entirely of characters from the\r | |
243 | string pointed to by s2.\r | |
244 | \r | |
245 | @return The strspn function returns the length of the segment.\r | |
246 | **/\r | |
247 | size_t strspn(const char *s1 , const char *s2);\r | |
248 | \r | |
249 | /** The strstr function locates the first occurrence in the string pointed to\r | |
250 | by s1 of the sequence of characters (excluding the terminating null\r | |
251 | character) in the string pointed to by s2.\r | |
252 | \r | |
253 | @return The strstr function returns a pointer to the located string, or a\r | |
254 | null pointer if the string is not found. If s2 points to a string\r | |
255 | with zero length, the function returns s1.\r | |
256 | **/\r | |
257 | char *strstr(const char *s1 , const char *s2);\r | |
258 | \r | |
259 | /** A sequence of calls to the strtok function breaks the string pointed to by\r | |
260 | s1 into a sequence of tokens, each of which is delimited by a character\r | |
261 | from the string pointed to by s2. The first call in the sequence has a\r | |
262 | non-null first argument; subsequent calls in the sequence have a null first\r | |
263 | argument. The separator string pointed to by s2 may be different from call\r | |
264 | to call.\r | |
265 | \r | |
266 | The first call in the sequence searches the string pointed to by s1 for the\r | |
267 | first character that is not contained in the current separator string\r | |
268 | pointed to by s2. If no such character is found, then there are no tokens\r | |
269 | in the string pointed to by s1 and the strtok function returns a null\r | |
270 | pointer. If such a character is found, it is the start of the first token.\r | |
271 | \r | |
272 | The strtok function then searches from there for a character that is\r | |
273 | contained in the current separator string. If no such character is found,\r | |
274 | the current token extends to the end of the string pointed to by s1, and\r | |
275 | subsequent searches for a token will return a null pointer. If such a\r | |
276 | character is found, it is overwritten by a null character, which terminates\r | |
277 | the current token. The strtok function saves a pointer to the following\r | |
278 | character, from which the next search for a token will start.\r | |
279 | \r | |
280 | Each subsequent call, with a null pointer as the value of the first\r | |
281 | argument, starts searching from the saved pointer and behaves as\r | |
282 | described above.\r | |
283 | \r | |
284 | @return The strtok function returns a pointer to the first character of a\r | |
285 | token, or a null pointer if there is no token.\r | |
286 | **/\r | |
287 | char *strtok(char * __restrict s1, const char * __restrict s2);\r | |
288 | \r | |
289 | /* ################ Miscellaneous Functions ########################### */\r | |
290 | \r | |
291 | /** The memset function copies the value of c (converted to an unsigned char)\r | |
292 | into each of the first n characters of the object pointed to by s.\r | |
293 | \r | |
294 | @return The memset function returns the value of s.\r | |
295 | **/\r | |
296 | void *memset(void *s, int c, size_t n);\r | |
297 | \r | |
298 | /** The strerror function maps the number in errnum to a message string.\r | |
299 | Typically, the values for errnum come from errno, but strerror shall map\r | |
300 | any value of type int to a message.\r | |
301 | \r | |
302 | The implementation shall behave as if no library function calls the\r | |
303 | strerror function.\r | |
304 | \r | |
305 | @return The strerror function returns a pointer to the string, the\r | |
306 | contents of which are locale specific. The array pointed to\r | |
307 | shall not be modified by the program, but may be overwritten by\r | |
308 | a subsequent call to the strerror function.\r | |
309 | **/\r | |
310 | char *strerror(int num);\r | |
311 | \r | |
312 | /** The strlen function computes the length of the string pointed to by s.\r | |
313 | \r | |
314 | @return The strlen function returns the number of characters that\r | |
315 | precede the terminating null character.\r | |
316 | **/\r | |
317 | size_t strlen(const char *);\r | |
318 | \r | |
319 | \r | |
320 | /* ################ BSD Compatibility Functions ####################### */\r | |
321 | \r | |
322 | char *strdup (const char *);\r | |
323 | int strerror_r(int, char *, size_t);\r | |
324 | int strcasecmp(const char *s1, const char *s2);\r | |
325 | void *memccpy (void *, const void *, int, size_t);\r | |
53e1e5c6 | 326 | int strncasecmp(const char *s1, const char *s2, size_t n);\r |
d7ce7006 | 327 | size_t strlcpy(char *destination, const char *source, size_t size);\r |
328 | size_t strlcat(char *destination, const char *source, size_t size);\r | |
53e1e5c6 | 329 | \r |
d7ce7006 | 330 | // bcopy is is a void function with the src/dest arguments reversed, being used in socket lib\r |
331 | #define bcopy(a,b,c) ( memcpy((void *)b, (const void *)a, (size_t)c))\r | |
53e1e5c6 | 332 | \r |
333 | // bcmp is same as memcmp, returns 0 for successful compare, non-zero otherwise\r | |
334 | #define bcmp(a,b,c) ( memcmp((void *)a, (void *)b, (size_t)c))\r | |
335 | \r | |
d7ce7006 | 336 | /*\r |
337 | * Get next token from string *stringp, where tokens are possibly-empty\r | |
338 | * strings separated by characters from delim.\r | |
339 | *\r | |
340 | * Writes NULs into the string at *stringp to end tokens.\r | |
341 | * delim need not remain constant from call to call.\r | |
342 | * On return, *stringp points past the last NUL written (if there might\r | |
343 | * be further tokens), or is NULL (if there are definitely no more tokens).\r | |
344 | *\r | |
345 | * If *stringp is NULL, strsep returns NULL.\r | |
346 | */\r | |
347 | char *\r | |
348 | strsep(\r | |
349 | register char **stringp,\r | |
350 | register const char *delim\r | |
351 | );\r | |
2aa62f2b | 352 | \r |
353 | __END_DECLS\r | |
354 | \r | |
355 | #endif /* _STRING_H */\r |