1 /*
2 * NT basis DLL
3 *
4 * This file contains the Rtl* API functions. These should be implementable.
5 *
6 * Copyright 1996-1998 Marcus Meissner
7 * Copyright 1999 Alex Korobka
8 * Copyright 2003 Thomas Mertes
9 * Crc32 code Copyright 1986 Gary S. Brown (Public domain)
10 *
11 * This library is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU Lesser General Public
13 * License as published by the Free Software Foundation; either
14 * version 2.1 of the License, or (at your option) any later version.
15 *
16 * This library is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with this library; if not, write to the Free Software
23 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
24 */
25
26 #include "config.h"
27 #include "wine/port.h"
28
29 #include <stdlib.h>
30 #include <stdarg.h>
31 #include <stdio.h>
32 #include <string.h>
33 #include "ntstatus.h"
34 #define NONAMELESSSTRUCT
35 #define WIN32_NO_STATUS
36 #include "windef.h"
37 #include "winternl.h"
38 #include "wine/debug.h"
39 #include "wine/exception.h"
40 #include "ntdll_misc.h"
41
42 WINE_DEFAULT_DEBUG_CHANNEL(ntdll);
43
44 static RTL_CRITICAL_SECTION peb_lock;
45 static RTL_CRITICAL_SECTION_DEBUG critsect_debug =
46 {
47 0, 0, &peb_lock,
48 { &critsect_debug.ProcessLocksList, &critsect_debug.ProcessLocksList },
49 0, 0, { (DWORD_PTR)(__FILE__ ": peb_lock") }
50 };
51 static RTL_CRITICAL_SECTION peb_lock = { &critsect_debug, -1, 0, 0, 0, 0 };
52
53 /* CRC polynomial 0xedb88320 */
54 static const DWORD CRC_table[256] =
55 {
56 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 0x706af48f,
57 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 0xe0d5e91e, 0x97d2d988,
58 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 0x90bf1d91, 0x1db71064, 0x6ab020f2,
59 0xf3b97148, 0x84be41de, 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7,
60 0x136c9856, 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
61 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 0xa2677172,
62 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 0x35b5a8fa, 0x42b2986c,
63 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 0x45df5c75, 0xdcd60dcf, 0xabd13d59,
64 0x26d930ac, 0x51de003a, 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423,
65 0xcfba9599, 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
66 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 0x01db7106,
67 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 0x9fbfe4a5, 0xe8b8d433,
68 0x7807c9a2, 0x0f00f934, 0x9609a88e, 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d,
69 0x91646c97, 0xe6635c01, 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e,
70 0x6c0695ed, 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
71 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 0xfbd44c65,
72 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 0x4adfa541, 0x3dd895d7,
73 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 0x346ed9fc, 0xad678846, 0xda60b8d0,
74 0x44042d73, 0x33031de5, 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa,
75 0xbe0b1010, 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
76 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 0x2eb40d81,
77 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 0x03b6e20c, 0x74b1d29a,
78 0xead54739, 0x9dd277af, 0x04db2615, 0x73dc1683, 0xe3630b12, 0x94643b84,
79 0x0d6d6a3e, 0x7a6a5aa8, 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1,
80 0xf00f9344, 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
81 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 0x67dd4acc,
82 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 0xd6d6a3e8, 0xa1d1937e,
83 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 0xa6bc5767, 0x3fb506dd, 0x48b2364b,
84 0xd80d2bda, 0xaf0a1b4c, 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55,
85 0x316e8eef, 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
86 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 0xb2bd0b28,
87 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 0x2cd99e8b, 0x5bdeae1d,
88 0x9b64c2b0, 0xec63f226, 0x756aa39c, 0x026d930a, 0x9c0906a9, 0xeb0e363f,
89 0x72076785, 0x05005713, 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38,
90 0x92d28e9b, 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
91 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 0x18b74777,
92 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 0x8f659eff, 0xf862ae69,
93 0x616bffd3, 0x166ccf45, 0xa00ae278, 0xd70dd2ee, 0x4e048354, 0x3903b3c2,
94 0xa7672661, 0xd06016f7, 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc,
95 0x40df0b66, 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
96 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 0xcdd70693,
97 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 0x5d681b02, 0x2a6f2b94,
98 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 0x2d02ef8d
99 };
100
101 /*
102 * resource functions
103 */
104
105 /***********************************************************************
106 * RtlInitializeResource (NTDLL.@)
107 *
108 * xxxResource() functions implement multiple-reader-single-writer lock.
109 * The code is based on information published in WDJ January 1999 issue.
110 */
111 void WINAPI RtlInitializeResource(LPRTL_RWLOCK rwl)
112 {
113 if( rwl )
114 {
115 rwl->iNumberActive = 0;
116 rwl->uExclusiveWaiters = 0;
117 rwl->uSharedWaiters = 0;
118 rwl->hOwningThreadId = 0;
119 rwl->dwTimeoutBoost = 0; /* no info on this one, default value is 0 */
120 RtlInitializeCriticalSection( &rwl->rtlCS );
121 rwl->rtlCS.DebugInfo->Spare[0] = (DWORD_PTR)(__FILE__ ": RTL_RWLOCK.rtlCS");
122 NtCreateSemaphore( &rwl->hExclusiveReleaseSemaphore, SEMAPHORE_ALL_ACCESS, NULL, 0, 65535 );
123 NtCreateSemaphore( &rwl->hSharedReleaseSemaphore, SEMAPHORE_ALL_ACCESS, NULL, 0, 65535 );
124 }
125 }
126
127
128 /***********************************************************************
129 * RtlDeleteResource (NTDLL.@)
130 */
131 void WINAPI RtlDeleteResource(LPRTL_RWLOCK rwl)
132 {
133 if( rwl )
134 {
135 RtlEnterCriticalSection( &rwl->rtlCS );
136 if( rwl->iNumberActive || rwl->uExclusiveWaiters || rwl->uSharedWaiters )
137 MESSAGE("Deleting active MRSW lock (%p), expect failure\n", rwl );
138 rwl->hOwningThreadId = 0;
139 rwl->uExclusiveWaiters = rwl->uSharedWaiters = 0;
140 rwl->iNumberActive = 0;
141 NtClose( rwl->hExclusiveReleaseSemaphore );
142 NtClose( rwl->hSharedReleaseSemaphore );
143 RtlLeaveCriticalSection( &rwl->rtlCS );
144 rwl->rtlCS.DebugInfo->Spare[0] = 0;
145 RtlDeleteCriticalSection( &rwl->rtlCS );
146 }
147 }
148
149
150 /***********************************************************************
151 * RtlAcquireResourceExclusive (NTDLL.@)
152 */
153 BYTE WINAPI RtlAcquireResourceExclusive(LPRTL_RWLOCK rwl, BYTE fWait)
154 {
155 BYTE retVal = 0;
156 if( !rwl ) return 0;
157
158 start:
159 RtlEnterCriticalSection( &rwl->rtlCS );
160 if( rwl->iNumberActive == 0 ) /* lock is free */
161 {
162 rwl->iNumberActive = -1;
163 retVal = 1;
164 }
165 else if( rwl->iNumberActive < 0 ) /* exclusive lock in progress */
166 {
167 if( rwl->hOwningThreadId == ULongToHandle(GetCurrentThreadId()) )
168 {
169 retVal = 1;
170 rwl->iNumberActive--;
171 goto done;
172 }
173 wait:
174 if( fWait )
175 {
176 NTSTATUS status;
177
178 rwl->uExclusiveWaiters++;
179
180 RtlLeaveCriticalSection( &rwl->rtlCS );
181 status = NtWaitForSingleObject( rwl->hExclusiveReleaseSemaphore, FALSE, NULL );
182 if( HIWORD(status) )
183 goto done;
184 goto start; /* restart the acquisition to avoid deadlocks */
185 }
186 }
187 else /* one or more shared locks are in progress */
188 if( fWait )
189 goto wait;
190
191 if( retVal == 1 )
192 rwl->hOwningThreadId = ULongToHandle(GetCurrentThreadId());
193 done:
194 RtlLeaveCriticalSection( &rwl->rtlCS );
195 return retVal;
196 }
197
198 /***********************************************************************
199 * RtlAcquireResourceShared (NTDLL.@)
200 */
201 BYTE WINAPI RtlAcquireResourceShared(LPRTL_RWLOCK rwl, BYTE fWait)
202 {
203 NTSTATUS status = STATUS_UNSUCCESSFUL;
204 BYTE retVal = 0;
205 if( !rwl ) return 0;
206
207 start:
208 RtlEnterCriticalSection( &rwl->rtlCS );
209 if( rwl->iNumberActive < 0 )
210 {
211 if( rwl->hOwningThreadId == ULongToHandle(GetCurrentThreadId()) )
212 {
213 rwl->iNumberActive--;
214 retVal = 1;
215 goto done;
216 }
217
218 if( fWait )
219 {
220 rwl->uSharedWaiters++;
221 RtlLeaveCriticalSection( &rwl->rtlCS );
222 status = NtWaitForSingleObject( rwl->hSharedReleaseSemaphore, FALSE, NULL );
223 if( HIWORD(status) )
224 goto done;
225 goto start;
226 }
227 }
228 else
229 {
230 if( status != STATUS_WAIT_0 ) /* otherwise RtlReleaseResource() has already done it */
231 rwl->iNumberActive++;
232 retVal = 1;
233 }
234 done:
235 RtlLeaveCriticalSection( &rwl->rtlCS );
236 return retVal;
237 }
238
239
240 /***********************************************************************
241 * RtlReleaseResource (NTDLL.@)
242 */
243 void WINAPI RtlReleaseResource(LPRTL_RWLOCK rwl)
244 {
245 RtlEnterCriticalSection( &rwl->rtlCS );
246
247 if( rwl->iNumberActive > 0 ) /* have one or more readers */
248 {
249 if( --rwl->iNumberActive == 0 )
250 {
251 if( rwl->uExclusiveWaiters )
252 {
253 wake_exclusive:
254 rwl->uExclusiveWaiters--;
255 NtReleaseSemaphore( rwl->hExclusiveReleaseSemaphore, 1, NULL );
256 }
257 }
258 }
259 else
260 if( rwl->iNumberActive < 0 ) /* have a writer, possibly recursive */
261 {
262 if( ++rwl->iNumberActive == 0 )
263 {
264 rwl->hOwningThreadId = 0;
265 if( rwl->uExclusiveWaiters )
266 goto wake_exclusive;
267 else
268 if( rwl->uSharedWaiters )
269 {
270 UINT n = rwl->uSharedWaiters;
271 rwl->iNumberActive = rwl->uSharedWaiters; /* prevent new writers from joining until
272 * all queued readers have done their thing */
273 rwl->uSharedWaiters = 0;
274 NtReleaseSemaphore( rwl->hSharedReleaseSemaphore, n, NULL );
275 }
276 }
277 }
278 RtlLeaveCriticalSection( &rwl->rtlCS );
279 }
280
281
282 /***********************************************************************
283 * RtlDumpResource (NTDLL.@)
284 */
285 void WINAPI RtlDumpResource(LPRTL_RWLOCK rwl)
286 {
287 if( rwl )
288 {
289 MESSAGE("RtlDumpResource(%p):\n\tactive count = %i\n\twaiting readers = %i\n\twaiting writers = %i\n",
290 rwl, rwl->iNumberActive, rwl->uSharedWaiters, rwl->uExclusiveWaiters );
291 if( rwl->iNumberActive )
292 MESSAGE("\towner thread = %p\n", rwl->hOwningThreadId );
293 }
294 }
295
296 /*
297 * misc functions
298 */
299
300 /******************************************************************************
301 * DbgPrint [NTDLL.@]
302 */
303 NTSTATUS WINAPIV DbgPrint(LPCSTR fmt, ...)
304 {
305 char buf[512];
306 __ms_va_list args;
307
308 __ms_va_start(args, fmt);
309 NTDLL__vsnprintf(buf, sizeof(buf), fmt, args);
310 __ms_va_end(args);
311
312 MESSAGE("DbgPrint says: %s",buf);
313 /* hmm, raise exception? */
314 return STATUS_SUCCESS;
315 }
316
317
318 /******************************************************************************
319 * DbgPrintEx [NTDLL.@]
320 */
321 NTSTATUS WINAPIV DbgPrintEx(ULONG iComponentId, ULONG Level, LPCSTR fmt, ...)
322 {
323 NTSTATUS ret;
324 __ms_va_list args;
325
326 __ms_va_start(args, fmt);
327 ret = vDbgPrintEx(iComponentId, Level, fmt, args);
328 __ms_va_end(args);
329 return ret;
330 }
331
332 /******************************************************************************
333 * vDbgPrintEx [NTDLL.@]
334 */
335 NTSTATUS WINAPI vDbgPrintEx( ULONG id, ULONG level, LPCSTR fmt, __ms_va_list args )
336 {
337 return vDbgPrintExWithPrefix( "", id, level, fmt, args );
338 }
339
340 /******************************************************************************
341 * vDbgPrintExWithPrefix [NTDLL.@]
342 */
343 NTSTATUS WINAPI vDbgPrintExWithPrefix( LPCSTR prefix, ULONG id, ULONG level, LPCSTR fmt, __ms_va_list args )
344 {
345 char buf[1024];
346
347 NTDLL__vsnprintf(buf, sizeof(buf), fmt, args);
348
349 switch (level & DPFLTR_MASK)
350 {
351 case DPFLTR_ERROR_LEVEL: ERR("%s%x: %s", prefix, id, buf); break;
352 case DPFLTR_WARNING_LEVEL: WARN("%s%x: %s", prefix, id, buf); break;
353 case DPFLTR_TRACE_LEVEL:
354 case DPFLTR_INFO_LEVEL:
355 default: TRACE("%s%x: %s", prefix, id, buf); break;
356 }
357 return STATUS_SUCCESS;
358 }
359
360 /******************************************************************************
361 * RtlAcquirePebLock [NTDLL.@]
362 */
363 VOID WINAPI RtlAcquirePebLock(void)
364 {
365 RtlEnterCriticalSection( &peb_lock );
366 }
367
368 /******************************************************************************
369 * RtlReleasePebLock [NTDLL.@]
370 */
371 VOID WINAPI RtlReleasePebLock(void)
372 {
373 RtlLeaveCriticalSection( &peb_lock );
374 }
375
376 /******************************************************************************
377 * RtlNewSecurityObject [NTDLL.@]
378 */
379 NTSTATUS WINAPI
380 RtlNewSecurityObject( PSECURITY_DESCRIPTOR ParentDescriptor,
381 PSECURITY_DESCRIPTOR CreatorDescriptor,
382 PSECURITY_DESCRIPTOR *NewDescriptor,
383 BOOLEAN IsDirectoryObject,
384 HANDLE Token,
385 PGENERIC_MAPPING GenericMapping )
386 {
387 FIXME("(%p %p %p %d %p %p) stub!\n", ParentDescriptor, CreatorDescriptor,
388 NewDescriptor, IsDirectoryObject, Token, GenericMapping);
389 return STATUS_NOT_IMPLEMENTED;
390 }
391
392 /******************************************************************************
393 * RtlDeleteSecurityObject [NTDLL.@]
394 */
395 NTSTATUS WINAPI
396 RtlDeleteSecurityObject( PSECURITY_DESCRIPTOR *ObjectDescriptor )
397 {
398 FIXME("(%p) stub!\n", ObjectDescriptor);
399 return STATUS_NOT_IMPLEMENTED;
400 }
401
402 /**************************************************************************
403 * _chkstk [NTDLL.@]
404 *
405 * Glorified "enter xxxx".
406 */
407 #ifdef __i386__
408 __ASM_STDCALL_FUNC( _chkstk, 0,
409 "negl %eax\n\t"
410 "addl %esp,%eax\n\t"
411 "xchgl %esp,%eax\n\t"
412 "movl 0(%eax),%eax\n\t" /* copy return address from old location */
413 "movl %eax,0(%esp)\n\t"
414 "ret" )
415 #endif
416
417 /**************************************************************************
418 * _alloca_probe [NTDLL.@]
419 *
420 * Glorified "enter xxxx".
421 */
422 #ifdef __i386__
423 __ASM_STDCALL_FUNC( _alloca_probe, 0,
424 "negl %eax\n\t"
425 "addl %esp,%eax\n\t"
426 "xchgl %esp,%eax\n\t"
427 "movl 0(%eax),%eax\n\t" /* copy return address from old location */
428 "movl %eax,0(%esp)\n\t"
429 "ret" )
430 #endif
431
432
433 /******************************************************************************
434 * RtlInitializeGenericTable [NTDLL.@]
435 */
436 PVOID WINAPI RtlInitializeGenericTable(PVOID pTable, PVOID arg2, PVOID arg3, PVOID arg4, PVOID arg5)
437 {
438 FIXME("(%p,%p,%p,%p,%p) stub!\n", pTable, arg2, arg3, arg4, arg5);
439 return NULL;
440 }
441
442 /******************************************************************************
443 * RtlEnumerateGenericTableWithoutSplaying [NTDLL.@]
444 */
445 PVOID RtlEnumerateGenericTableWithoutSplaying(PVOID pTable, PVOID *RestartKey)
446 {
447 FIXME("(%p,%p) stub!\n", pTable, RestartKey);
448 return NULL;
449 }
450
451 /******************************************************************************
452 * RtlMoveMemory [NTDLL.@]
453 *
454 * Move a block of memory that may overlap.
455 *
456 * PARAMS
457 * Destination [O] End destination for block
458 * Source [O] Where to start copying from
459 * Length [I] Number of bytes to copy
460 *
461 * RETURNS
462 * Nothing.
463 */
464 #undef RtlMoveMemory
465 VOID WINAPI RtlMoveMemory( VOID *Destination, CONST VOID *Source, SIZE_T Length )
466 {
467 memmove(Destination, Source, Length);
468 }
469
470 /******************************************************************************
471 * RtlFillMemory [NTDLL.@]
472 *
473 * Set a block of memory with a value.
474 *
475 * PARAMS
476 * Destination [O] Block to fill
477 * Length [I] Number of bytes to fill
478 * Fill [I] Value to set
479 *
480 * RETURNS
481 * Nothing.
482 */
483 #undef RtlFillMemory
484 VOID WINAPI RtlFillMemory( VOID *Destination, SIZE_T Length, BYTE Fill )
485 {
486 memset(Destination, Fill, Length);
487 }
488
489 /******************************************************************************
490 * RtlZeroMemory [NTDLL.@]
491 *
492 * Set a block of memory with 0's.
493 *
494 * PARAMS
495 * Destination [O] Block to fill
496 * Length [I] Number of bytes to fill
497 *
498 * RETURNS
499 * Nothing.
500 */
501 #undef RtlZeroMemory
502 VOID WINAPI RtlZeroMemory( VOID *Destination, SIZE_T Length )
503 {
504 memset(Destination, 0, Length);
505 }
506
507 /******************************************************************************
508 * RtlCompareMemory [NTDLL.@]
509 *
510 * Compare one block of memory with another
511 *
512 * PARAMS
513 * Source1 [I] Source block
514 * Source2 [I] Block to compare to Source1
515 * Length [I] Number of bytes to compare
516 *
517 * RETURNS
518 * The length of the first byte at which Source1 and Source2 differ, or Length
519 * if they are the same.
520 */
521 SIZE_T WINAPI RtlCompareMemory( const VOID *Source1, const VOID *Source2, SIZE_T Length)
522 {
523 SIZE_T i;
524 for(i=0; (i<Length) && (((const BYTE*)Source1)[i]==((const BYTE*)Source2)[i]); i++);
525 return i;
526 }
527
528 /******************************************************************************
529 * RtlCompareMemoryUlong [NTDLL.@]
530 *
531 * Compare a block of memory with a value, a ULONG at a time
532 *
533 * PARAMS
534 * Source1 [I] Source block. This must be ULONG aligned
535 * Length [I] Number of bytes to compare. This should be a multiple of 4
536 * dwVal [I] Value to compare to
537 *
538 * RETURNS
539 * The byte position of the first byte at which Source1 is not dwVal.
540 */
541 SIZE_T WINAPI RtlCompareMemoryUlong(const ULONG *Source1, SIZE_T Length, ULONG dwVal)
542 {
543 SIZE_T i;
544 for(i = 0; i < Length/sizeof(ULONG) && Source1[i] == dwVal; i++);
545 return i * sizeof(ULONG);
546 }
547
548 /******************************************************************************
549 * RtlAssert [NTDLL.@]
550 *
551 * Fail a debug assertion.
552 *
553 * RETURNS
554 * Nothing. This call does not return control to its caller.
555 *
556 * NOTES
557 * Not implemented in non-debug versions.
558 */
559 void WINAPI RtlAssert(LPVOID x1,LPVOID x2,DWORD x3, DWORD x4)
560 {
561 FIXME("(%p,%p,0x%08x,0x%08x),stub\n",x1,x2,x3,x4);
562 }
563
564 /*************************************************************************
565 * RtlFillMemoryUlong [NTDLL.@]
566 *
567 * Fill memory with a 32 bit (dword) value.
568 *
569 * PARAMS
570 * lpDest [I] Bitmap pointer
571 * ulCount [I] Number of dwords to write
572 * ulValue [I] Value to fill with
573 *
574 * RETURNS
575 * Nothing.
576 */
577 VOID WINAPI RtlFillMemoryUlong(ULONG* lpDest, ULONG ulCount, ULONG ulValue)
578 {
579 TRACE("(%p,%d,%d)\n", lpDest, ulCount, ulValue);
580
581 ulCount /= sizeof(ULONG);
582 while(ulCount--)
583 *lpDest++ = ulValue;
584 }
585
586 /*********************************************************************
587 * RtlComputeCrc32 [NTDLL.@]
588 *
589 * Calculate the CRC32 checksum of a block of bytes
590 *
591 * PARAMS
592 * dwInitial [I] Initial CRC value
593 * pData [I] Data block
594 * iLen [I] Length of the byte block
595 *
596 * RETURNS
597 * The cumulative CRC32 of dwInitial and iLen bytes of the pData block.
598 */
599 DWORD WINAPI RtlComputeCrc32(DWORD dwInitial, const BYTE *pData, INT iLen)
600 {
601 DWORD crc = ~dwInitial;
602
603 TRACE("(%d,%p,%d)\n", dwInitial, pData, iLen);
604
605 while (iLen > 0)
606 {
607 crc = CRC_table[(crc ^ *pData) & 0xff] ^ (crc >> 8);
608 pData++;
609 iLen--;
610 }
611 return ~crc;
612 }
613
614
615 /*************************************************************************
616 * RtlUlonglongByteSwap [NTDLL.@]
617 *
618 * Swap the bytes of an unsigned long long value.
619 *
620 * PARAMS
621 * i [I] Value to swap bytes of
622 *
623 * RETURNS
624 * The value with its bytes swapped.
625 */
626 ULONGLONG __cdecl RtlUlonglongByteSwap(ULONGLONG i)
627 {
628 return ((ULONGLONG)RtlUlongByteSwap(i) << 32) | RtlUlongByteSwap(i>>32);
629 }
630
631 /*************************************************************************
632 * RtlUlongByteSwap [NTDLL.@]
633 *
634 * Swap the bytes of an unsigned int value.
635 *
636 * NOTES
637 * ix86 version takes argument in %ecx. Other systems use the inline version.
638 */
639 #ifdef __i386__
640 __ASM_GLOBAL_FUNC(NTDLL_RtlUlongByteSwap,
641 "movl %ecx,%eax\n\t"
642 "bswap %eax\n\t"
643 "ret")
644 #endif
645
646 /*************************************************************************
647 * RtlUshortByteSwap [NTDLL.@]
648 *
649 * Swap the bytes of an unsigned short value.
650 *
651 * NOTES
652 * i386 version takes argument in %cx. Other systems use the inline version.
653 */
654 #ifdef __i386__
655 __ASM_GLOBAL_FUNC(NTDLL_RtlUshortByteSwap,
656 "movb %ch,%al\n\t"
657 "movb %cl,%ah\n\t"
658 "ret")
659 #endif
660
661
662 /*************************************************************************
663 * RtlUniform [NTDLL.@]
664 *
665 * Generates an uniform random number
666 *
667 * PARAMS
668 * seed [O] The seed of the Random function
669 *
670 * RETURNS
671 * It returns a random number uniformly distributed over [0..MAXLONG-1].
672 *
673 * NOTES
674 * Generates an uniform random number using D.H. Lehmer's 1948 algorithm.
675 * In our case the algorithm is:
676 *
677 *| result = (*seed * 0x7fffffed + 0x7fffffc3) % MAXLONG;
678 *|
679 *| *seed = result;
680 *
681 * DIFFERENCES
682 * The native documentation states that the random number is
683 * uniformly distributed over [0..MAXLONG]. In reality the native
684 * function and our function return a random number uniformly
685 * distributed over [0..MAXLONG-1].
686 */
687 ULONG WINAPI RtlUniform (PULONG seed)
688 {
689 ULONG result;
690
691 /*
692 * Instead of the algorithm stated above, we use the algorithm
693 * below, which is totally equivalent (see the tests), but does
694 * not use a division and therefore is faster.
695 */
696 result = *seed * 0xffffffed + 0x7fffffc3;
697 if (result == 0xffffffff || result == 0x7ffffffe) {
698 result = (result + 2) & MAXLONG;
699 } else if (result == 0x7fffffff) {
700 result = 0;
701 } else if ((result & 0x80000000) == 0) {
702 result = result + (~result & 1);
703 } else {
704 result = (result + (result & 1)) & MAXLONG;
705 } /* if */
706 *seed = result;
707 return result;
708 }
709
710
711 /*************************************************************************
712 * RtlRandom [NTDLL.@]
713 *
714 * Generates a random number
715 *
716 * PARAMS
717 * seed [O] The seed of the Random function
718 *
719 * RETURNS
720 * It returns a random number distributed over [0..MAXLONG-1].
721 */
722 ULONG WINAPI RtlRandom (PULONG seed)
723 {
724 static ULONG saved_value[128] =
725 { /* 0 */ 0x4c8bc0aa, 0x4c022957, 0x2232827a, 0x2f1e7626, 0x7f8bdafb, 0x5c37d02a, 0x0ab48f72, 0x2f0c4ffa,
726 /* 8 */ 0x290e1954, 0x6b635f23, 0x5d3885c0, 0x74b49ff8, 0x5155fa54, 0x6214ad3f, 0x111e9c29, 0x242a3a09,
727 /* 16 */ 0x75932ae1, 0x40ac432e, 0x54f7ba7a, 0x585ccbd5, 0x6df5c727, 0x0374dad1, 0x7112b3f1, 0x735fc311,
728 /* 24 */ 0x404331a9, 0x74d97781, 0x64495118, 0x323e04be, 0x5974b425, 0x4862e393, 0x62389c1d, 0x28a68b82,
729 /* 32 */ 0x0f95da37, 0x7a50bbc6, 0x09b0091c, 0x22cdb7b4, 0x4faaed26, 0x66417ccd, 0x189e4bfa, 0x1ce4e8dd,
730 /* 40 */ 0x5274c742, 0x3bdcf4dc, 0x2d94e907, 0x32eac016, 0x26d33ca3, 0x60415a8a, 0x31f57880, 0x68c8aa52,
731 /* 48 */ 0x23eb16da, 0x6204f4a1, 0x373927c1, 0x0d24eb7c, 0x06dd7379, 0x2b3be507, 0x0f9c55b1, 0x2c7925eb,
732 /* 56 */ 0x36d67c9a, 0x42f831d9, 0x5e3961cb, 0x65d637a8, 0x24bb3820, 0x4d08e33d, 0x2188754f, 0x147e409e,
733 /* 64 */ 0x6a9620a0, 0x62e26657, 0x7bd8ce81, 0x11da0abb, 0x5f9e7b50, 0x23e444b6, 0x25920c78, 0x5fc894f0,
734 /* 72 */ 0x5e338cbb, 0x404237fd, 0x1d60f80f, 0x320a1743, 0x76013d2b, 0x070294ee, 0x695e243b, 0x56b177fd,
735 /* 80 */ 0x752492e1, 0x6decd52f, 0x125f5219, 0x139d2e78, 0x1898d11e, 0x2f7ee785, 0x4db405d8, 0x1a028a35,
736 /* 88 */ 0x63f6f323, 0x1f6d0078, 0x307cfd67, 0x3f32a78a, 0x6980796c, 0x462b3d83, 0x34b639f2, 0x53fce379,
737 /* 96 */ 0x74ba50f4, 0x1abc2c4b, 0x5eeaeb8d, 0x335a7a0d, 0x3973dd20, 0x0462d66b, 0x159813ff, 0x1e4643fd,
738 /* 104 */ 0x06bc5c62, 0x3115e3fc, 0x09101613, 0x47af2515, 0x4f11ec54, 0x78b99911, 0x3db8dd44, 0x1ec10b9b,
739 /* 112 */ 0x5b5506ca, 0x773ce092, 0x567be81a, 0x5475b975, 0x7a2cde1a, 0x494536f5, 0x34737bb4, 0x76d9750b,
740 /* 120 */ 0x2a1f6232, 0x2e49644d, 0x7dddcbe7, 0x500cebdb, 0x619dab9e, 0x48c626fe, 0x1cda3193, 0x52dabe9d };
741 ULONG rand;
742 int pos;
743 ULONG result;
744
745 rand = (*seed * 0x7fffffed + 0x7fffffc3) % 0x7fffffff;
746 *seed = (rand * 0x7fffffed + 0x7fffffc3) % 0x7fffffff;
747 pos = *seed & 0x7f;
748 result = saved_value[pos];
749 saved_value[pos] = rand;
750 return(result);
751 }
752
753
754 /*************************************************************************
755 * RtlAreAllAccessesGranted [NTDLL.@]
756 *
757 * Check if all desired accesses are granted
758 *
759 * RETURNS
760 * TRUE: All desired accesses are granted
761 * FALSE: Otherwise
762 */
763 BOOLEAN WINAPI RtlAreAllAccessesGranted(
764 ACCESS_MASK GrantedAccess,
765 ACCESS_MASK DesiredAccess)
766 {
767 return (GrantedAccess & DesiredAccess) == DesiredAccess;
768 }
769
770
771 /*************************************************************************
772 * RtlAreAnyAccessesGranted [NTDLL.@]
773 *
774 * Check if at least one of the desired accesses is granted
775 *
776 * PARAMS
777 * GrantedAccess [I] Access mask of granted accesses
778 * DesiredAccess [I] Access mask of desired accesses
779 *
780 * RETURNS
781 * TRUE: At least one of the desired accesses is granted
782 * FALSE: Otherwise
783 */
784 BOOLEAN WINAPI RtlAreAnyAccessesGranted(
785 ACCESS_MASK GrantedAccess,
786 ACCESS_MASK DesiredAccess)
787 {
788 return (GrantedAccess & DesiredAccess) != 0;
789 }
790
791
792 /*************************************************************************
793 * RtlMapGenericMask [NTDLL.@]
794 *
795 * Determine the nongeneric access rights specified by an access mask
796 *
797 * RETURNS
798 * Nothing.
799 */
800 void WINAPI RtlMapGenericMask(
801 PACCESS_MASK AccessMask,
802 const GENERIC_MAPPING *GenericMapping)
803 {
804 if (*AccessMask & GENERIC_READ) {
805 *AccessMask |= GenericMapping->GenericRead;
806 } /* if */
807
808 if (*AccessMask & GENERIC_WRITE) {
809 *AccessMask |= GenericMapping->GenericWrite;
810 } /* if */
811
812 if (*AccessMask & GENERIC_EXECUTE) {
813 *AccessMask |= GenericMapping->GenericExecute;
814 } /* if */
815
816 if (*AccessMask & GENERIC_ALL) {
817 *AccessMask |= GenericMapping->GenericAll;
818 } /* if */
819
820 *AccessMask &= 0x0FFFFFFF;
821 }
822
823
824 /*************************************************************************
825 * RtlCopyLuid [NTDLL.@]
826 *
827 * Copy a local unique ID.
828 *
829 * PARAMS
830 * LuidDest [O] Destination for the copied Luid
831 * LuidSrc [I] Source Luid to copy to LuidDest
832 *
833 * RETURNS
834 * Nothing.
835 */
836 void WINAPI RtlCopyLuid (PLUID LuidDest, const LUID *LuidSrc)
837 {
838 *LuidDest = *LuidSrc;
839 }
840
841
842 /*************************************************************************
843 * RtlEqualLuid [NTDLL.@]
844 *
845 * Compare two local unique ID's.
846 *
847 * PARAMS
848 * Luid1 [I] First Luid to compare to Luid2
849 * Luid2 [I] Second Luid to compare to Luid1
850 *
851 * RETURNS
852 * TRUE: The two LUID's are equal.
853 * FALSE: Otherwise
854 */
855 BOOLEAN WINAPI RtlEqualLuid (const LUID *Luid1, const LUID *Luid2)
856 {
857 return (Luid1->LowPart == Luid2->LowPart && Luid1->HighPart == Luid2->HighPart);
858 }
859
860
861 /*************************************************************************
862 * RtlCopyLuidAndAttributesArray [NTDLL.@]
863 *
864 * Copy an array of local unique ID's and attributes.
865 *
866 * PARAMS
867 * Count [I] Number of Luid/attributes in Src
868 * Src [I] Source Luid/attributes to copy
869 * Dest [O] Destination for copied Luid/attributes
870 *
871 * RETURNS
872 * Nothing.
873 *
874 * NOTES
875 * Dest must be large enough to hold Src.
876 */
877 void WINAPI RtlCopyLuidAndAttributesArray(
878 ULONG Count,
879 const LUID_AND_ATTRIBUTES *Src,
880 PLUID_AND_ATTRIBUTES Dest)
881 {
882 ULONG i;
883
884 for (i = 0; i < Count; i++) Dest[i] = Src[i];
885 }
886
887 NTSTATUS WINAPI RtlIpv4StringToAddressExW(PULONG IP, PULONG Port,
888 LPCWSTR Buffer, PULONG MaxSize)
889 {
890 FIXME("(%p,%p,%p,%p): stub\n", IP, Port, Buffer, MaxSize);
891
892 return STATUS_SUCCESS;
893 }
894
895 NTSTATUS WINAPI RtlIpv4AddressToStringExW (PULONG IP, PULONG Port,
896 LPWSTR Buffer, PULONG MaxSize)
897 {
898 FIXME("(%p,%p,%p,%p): stub\n", IP, Port, Buffer, MaxSize);
899
900 return STATUS_SUCCESS;
901 }
902
903 static DWORD_PTR get_pointer_obfuscator( void )
904 {
905 static DWORD_PTR pointer_obfuscator;
906
907 if (!pointer_obfuscator)
908 {
909 ULONG seed = NtGetTickCount();
910 ULONG_PTR rand;
911
912 /* generate a random value for the obfuscator */
913 rand = RtlUniform( &seed );
914
915 /* handle 64bit pointers */
916 rand ^= (ULONG_PTR)RtlUniform( &seed ) << ((sizeof (DWORD_PTR) - sizeof (ULONG))*8);
917
918 /* set the high bits so dereferencing obfuscated pointers will (usually) crash */
919 rand |= (ULONG_PTR)0xc0000000 << ((sizeof (DWORD_PTR) - sizeof (ULONG))*8);
920
921 interlocked_cmpxchg_ptr( (void**) &pointer_obfuscator, (void*) rand, NULL );
922 }
923
924 return pointer_obfuscator;
925 }
926
927 /*************************************************************************
928 * RtlEncodePointer [NTDLL.@]
929 */
930 PVOID WINAPI RtlEncodePointer( PVOID ptr )
931 {
932 DWORD_PTR ptrval = (DWORD_PTR) ptr;
933 return (PVOID)(ptrval ^ get_pointer_obfuscator());
934 }
935
936 PVOID WINAPI RtlDecodePointer( PVOID ptr )
937 {
938 DWORD_PTR ptrval = (DWORD_PTR) ptr;
939 return (PVOID)(ptrval ^ get_pointer_obfuscator());
940 }
941
942 /*************************************************************************
943 * RtlInitializeSListHead [NTDLL.@]
944 */
945 VOID WINAPI RtlInitializeSListHead(PSLIST_HEADER list)
946 {
947 #ifdef _WIN64
948 list->s.Alignment = list->s.Region = 0;
949 list->Header16.HeaderType = 1; /* we use the 16-byte header */
950 #else
951 list->Alignment = 0;
952 #endif
953 }
954
955 /*************************************************************************
956 * RtlQueryDepthSList [NTDLL.@]
957 */
958 WORD WINAPI RtlQueryDepthSList(PSLIST_HEADER list)
959 {
960 #ifdef _WIN64
961 return list->Header16.Depth;
962 #else
963 return list->s.Depth;
964 #endif
965 }
966
967 /*************************************************************************
968 * RtlFirstEntrySList [NTDLL.@]
969 */
970 PSLIST_ENTRY WINAPI RtlFirstEntrySList(const SLIST_HEADER* list)
971 {
972 #ifdef _WIN64
973 return (SLIST_ENTRY *)((ULONG_PTR)list->Header16.NextEntry << 4);
974 #else
975 return list->s.Next.Next;
976 #endif
977 }
978
979 /*************************************************************************
980 * RtlInterlockedFlushSList [NTDLL.@]
981 */
982 PSLIST_ENTRY WINAPI RtlInterlockedFlushSList(PSLIST_HEADER list)
983 {
984 SLIST_HEADER old, new;
985
986 #ifdef _WIN64
987 if (!list->Header16.Depth) return NULL;
988 new.s.Alignment = new.s.Region = 0;
989 new.Header16.HeaderType = 1; /* we use the 16-byte header */
990 do
991 {
992 old = *list;
993 new.Header16.Sequence = old.Header16.Sequence + 1;
994 } while (!interlocked_cmpxchg128((__int64 *)list, new.s.Region, new.s.Alignment, (__int64 *)&old));
995 return (SLIST_ENTRY *)((ULONG_PTR)old.Header16.NextEntry << 4);
996 #else
997 if (!list->s.Depth) return NULL;
998 new.Alignment = 0;
999 do
1000 {
1001 old = *list;
1002 new.s.Sequence = old.s.Sequence + 1;
1003 } while (interlocked_cmpxchg64((__int64 *)&list->Alignment, new.Alignment,
1004 old.Alignment) != old.Alignment);
1005 return old.s.Next.Next;
1006 #endif
1007 }
1008
1009 /*************************************************************************
1010 * RtlInterlockedPushEntrySList [NTDLL.@]
1011 */
1012 PSLIST_ENTRY WINAPI RtlInterlockedPushEntrySList(PSLIST_HEADER list, PSLIST_ENTRY entry)
1013 {
1014 SLIST_HEADER old, new;
1015
1016 #ifdef _WIN64
1017 new.Header16.NextEntry = (ULONG_PTR)entry >> 4;
1018 do
1019 {
1020 old = *list;
1021 entry->Next = (SLIST_ENTRY *)((ULONG_PTR)old.Header16.NextEntry << 4);
1022 new.Header16.Depth = old.Header16.Depth + 1;
1023 new.Header16.Sequence = old.Header16.Sequence + 1;
1024 } while (!interlocked_cmpxchg128((__int64 *)list, new.s.Region, new.s.Alignment, (__int64 *)&old));
1025 return (SLIST_ENTRY *)((ULONG_PTR)old.Header16.NextEntry << 4);
1026 #else
1027 new.s.Next.Next = entry;
1028 do
1029 {
1030 old = *list;
1031 entry->Next = old.s.Next.Next;
1032 new.s.Depth = old.s.Depth + 1;
1033 new.s.Sequence = old.s.Sequence + 1;
1034 } while (interlocked_cmpxchg64((__int64 *)&list->Alignment, new.Alignment,
1035 old.Alignment) != old.Alignment);
1036 return old.s.Next.Next;
1037 #endif
1038 }
1039
1040 /*************************************************************************
1041 * RtlInterlockedPopEntrySList [NTDLL.@]
1042 */
1043 PSLIST_ENTRY WINAPI RtlInterlockedPopEntrySList(PSLIST_HEADER list)
1044 {
1045 SLIST_HEADER old, new;
1046 PSLIST_ENTRY entry;
1047
1048 #ifdef _WIN64
1049 do
1050 {
1051 old = *list;
1052 if (!(entry = (SLIST_ENTRY *)((ULONG_PTR)old.Header16.NextEntry << 4))) return NULL;
1053 /* entry could be deleted by another thread */
1054 __TRY
1055 {
1056 new.Header16.NextEntry = (ULONG_PTR)entry->Next >> 4;
1057 new.Header16.Depth = old.Header16.Depth - 1;
1058 new.Header16.Sequence = old.Header16.Sequence + 1;
1059 }
1060 __EXCEPT_PAGE_FAULT
1061 {
1062 }
1063 __ENDTRY
1064 } while (!interlocked_cmpxchg128((__int64 *)list, new.s.Region, new.s.Alignment, (__int64 *)&old));
1065 #else
1066 do
1067 {
1068 old = *list;
1069 if (!(entry = old.s.Next.Next)) return NULL;
1070 /* entry could be deleted by another thread */
1071 __TRY
1072 {
1073 new.s.Next.Next = entry->Next;
1074 new.s.Depth = old.s.Depth - 1;
1075 new.s.Sequence = old.s.Sequence + 1;
1076 }
1077 __EXCEPT_PAGE_FAULT
1078 {
1079 }
1080 __ENDTRY
1081 } while (interlocked_cmpxchg64((__int64 *)&list->Alignment, new.Alignment,
1082 old.Alignment) != old.Alignment);
1083 #endif
1084 return entry;
1085 }
1086
1087 /*************************************************************************
1088 * RtlInterlockedPushListSList [NTDLL.@]
1089 */
1090 PSLIST_ENTRY WINAPI RtlInterlockedPushListSList(PSLIST_HEADER list, PSLIST_ENTRY first,
1091 PSLIST_ENTRY last, ULONG count)
1092 {
1093 SLIST_HEADER old, new;
1094
1095 #ifdef _WIN64
1096 new.Header16.NextEntry = (ULONG_PTR)first >> 4;
1097 do
1098 {
1099 old = *list;
1100 new.Header16.Depth = old.Header16.Depth + count;
1101 new.Header16.Sequence = old.Header16.Sequence + 1;
1102 last->Next = (SLIST_ENTRY *)((ULONG_PTR)old.Header16.NextEntry << 4);
1103 } while (!interlocked_cmpxchg128((__int64 *)list, new.s.Region, new.s.Alignment, (__int64 *)&old));
1104 return (SLIST_ENTRY *)((ULONG_PTR)old.Header16.NextEntry << 4);
1105 #else
1106 new.s.Next.Next = first;
1107 do
1108 {
1109 old = *list;
1110 new.s.Depth = old.s.Depth + count;
1111 new.s.Sequence = old.s.Sequence + 1;
1112 last->Next = old.s.Next.Next;
1113 } while (interlocked_cmpxchg64((__int64 *)&list->Alignment, new.Alignment,
1114 old.Alignment) != old.Alignment);
1115 return old.s.Next.Next;
1116 #endif
1117 }
1118
1119 /******************************************************************************
1120 * RtlGetCompressionWorkSpaceSize [NTDLL.@]
1121 */
1122 NTSTATUS WINAPI RtlGetCompressionWorkSpaceSize(USHORT CompressionFormatAndEngine,
1123 PULONG CompressBufferWorkSpaceSize,
1124 PULONG CompressFragmentWorkSpaceSize)
1125 {
1126 FIXME("0x%04x, %p, %p: stub!\n", CompressionFormatAndEngine, CompressBufferWorkSpaceSize,
1127 CompressFragmentWorkSpaceSize);
1128
1129 return STATUS_NOT_IMPLEMENTED;
1130 }
1131
1132 /******************************************************************************
1133 * RtlCompressBuffer [NTDLL.@]
1134 */
1135 NTSTATUS WINAPI RtlCompressBuffer(USHORT CompressionFormatAndEngine, PUCHAR UncompressedBuffer,
1136 ULONG UncompressedBufferSize, PUCHAR CompressedBuffer,
1137 ULONG CompressedBufferSize, ULONG UncompressedChunkSize,
1138 PULONG FinalCompressedSize, PVOID WorkSpace)
1139 {
1140 FIXME("0x%04x, %p, %u, %p, %u, %u, %p, %p :stub\n", CompressionFormatAndEngine, UncompressedBuffer,
1141 UncompressedBufferSize, CompressedBuffer, CompressedBufferSize, UncompressedChunkSize,
1142 FinalCompressedSize, WorkSpace);
1143
1144 return STATUS_NOT_IMPLEMENTED;
1145 }
1146
1147 /******************************************************************************
1148 * RtlDecompressBuffer [NTDLL.@]
1149 */
1150 NTSTATUS WINAPI RtlDecompressBuffer(USHORT CompressionFormat, PUCHAR UncompressedBuffer,
1151 ULONG UncompressedBufferSize, PUCHAR CompressedBuffer,
1152 ULONG CompressedBufferSize, PULONG FinalUncompressedSize)
1153 {
1154 FIXME("0x%04x, %p, %u, %p, %u, %p :stub\n", CompressionFormat, UncompressedBuffer, UncompressedBufferSize,
1155 CompressedBuffer, CompressedBufferSize, FinalUncompressedSize);
1156
1157 return STATUS_NOT_IMPLEMENTED;
1158 }
1159
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.