Mercurial > illumos > illumos-gate

comparison usr/src/lib/libkmsagent/common/SYSCommon.h @ 12720:3db6e0082404

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
PSARC 2010/195 PKCS11 KMS Provider 6944296 Solaris needs a PKCS#11 provider to allow access to KMS keystore functionality
author Wyllys Ingersoll <Wyllys.Ingersoll@Sun.COM>
date Mon, 28 Jun 2010 16:04:11 -0700
parents
children
comparison
equal deleted inserted replaced
12719:bd9fb35d09c2 12720:3db6e0082404
1 /*
2 * CDDL HEADER START
3 *
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License (the "License").
6 * You may not use this file except in compliance with the License.
7 *
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21
22 /*
23 * Copyright (c) 2007, 2010, Oracle and/or its affiliates. All rights reserved.
24 */
25
26 /*---------------------------------------------------------------------------
27 * Module: System Abstraction Layer
28 *
29 * Description:
30 * The system layer provides an abstract layer for the most commonly
31 * used system calls for multi-platforms including Windows and most
32 * Unix variants.
33 *
34 * All the functions defined in this layer fall into 4 categories:
35 * Threading related functions
36 * Mutexes
37 * Conditional variables
38 * Other Utilities
39 *--------------------------------------------------------------------------*/
40
41 #ifndef SYS_COMMON_H
42 #define SYS_COMMON_H
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46
47 /*---------------------------------------------------------------------------
48 * ERROR code
49 *--------------------------------------------------------------------------*/
50
51 #define K_SYS_OK 0
52 #define K_SYS_ERR_NO_MEMORY 1
53 #define K_SYS_ERR_CREATE_THREAD 2
54 #define K_SYS_ERR_JOIN_THREAD 3
55 #define K_SYS_ERR_COND 4
56
57 /*---------------------------------------------------------------------------
58 * Header files
59 *--------------------------------------------------------------------------*/
60
61 #ifdef WIN32
62 #include <windows.h>
63 #include <process.h>
64 #else
65 #include <pthread.h>
66
67 /* UNIX : added by STG */
68 #include <stdlib.h>
69 #include <string.h>
70 #ifndef METAWARE
71 #include <wchar.h>
72 #endif
73 #include <sys/types.h>
74 #include <sys/stat.h>
75 #include <stdarg.h>
76
77 /*
78 * These functions are not needed, since the Agent API hides them
79 * enum KeystoneAgent_SortOrder {};
80 * enum KeystoneAgent_FilterOperator {};
81 */
82
83 #endif
84
85 /*---------------------------------------------------------------------------
86 * MACRO definitions
87 *--------------------------------------------------------------------------*/
88
89 #ifdef WIN32
90 #define PATH_SEPARATOR '\\'
91 #define PATH_SEPARATOR_WSTR L"\\"
92 #ifndef PATH_MAX
93 #define PATH_MAX MAX_PATH
94 #endif
95 #else
96 #define PATH_SEPARATOR '/'
97 #define PATH_SEPARATOR_WSTR L"/"
98 #endif
99
100 #ifndef BOOL
101 #define BOOL int
102 #endif
103 #ifndef TRUE
104 #define TRUE 1
105 #define FALSE 0
106 #endif
107
108 #ifdef K_LINUX_PLATFORM
109 #ifndef UNIX
110 #define UNIX
111 #endif
112 #endif
113
114 #ifdef K_AIX_PLATFORM
115 #ifndef UNIX
116 #define UNIX
117 #endif
118 #endif
119
120 #ifdef K_SOLARIS_PLATFORM
121 #ifndef UNIX
122 #define UNIX
123 #endif
124 #endif
125
126 #ifdef K_HPUX_PLATFORM
127 #ifndef UNIX
128 #define UNIX
129 #endif
130 #endif
131
132 /*---------------------------------------------------------------------------
133 * Fatal error definitions
134 *--------------------------------------------------------------------------*/
135
136 #ifndef __FUNCTION__
137 #define __FUNCTION__ "(Unknown)"
138 #endif
139
140 #ifndef FATAL_APPLICATION_STATE
141
142 #ifdef DEBUG
143
144 #ifdef WIN32
145 #include "crtdbg.h"
146 #define DEBUG_BREAK() { _CrtDbgBreak(); }
147 #else /* WIN32 */
148 #ifdef METAWARE
149 #define DEBUG_BREAK() (void *) 0x00000000; /* dummy operation */
150 #else
151 #if !defined(__i386)
152 #define DEBUG_BREAK()
153 #else
154 #ifdef __GNUC__
155 #define DEBUG_BREAK() { __asm__ ( "int3" ); } /* NOTE: This only works for x86 platforms */
156 #else
157 #define DEBUG_BREAK()
158 #endif
159 #endif /* __i386 */
160 #endif /* METAWARE */
161 #endif /* WIN32 */
162
163 #define FATAL_APPLICATION_STATE() \
164 do { \
165 DEBUG_BREAK(); \
166 process_fatal_application_state(__FILE__,__FUNCTION__,__LINE__,0); \
167 } while(0)
168
169 #define FATAL_APPLICATION_STATE1(additional_text) \
170 do { \
171 DEBUG_BREAK(); \
172 process_fatal_application_state(__FILE__,__FUNCTION__,__LINE__,additional_text); \
173 } while(0)
174
175 #else //DEBUG
176
177 #define DEBUG_BREAK()
178
179 #define FATAL_APPLICATION_STATE() \
180 do { \
181 process_fatal_application_state(__FILE__,__FUNCTION__,__LINE__,0); \
182 } while(0)
183
184 #define FATAL_APPLICATION_STATE1(additional_text) \
185 do { \
186 process_fatal_application_state(__FILE__,__FUNCTION__,__LINE__,additional_text); \
187 } while(0)
188
189 #endif //DEBUG
190
191 #define FATAL_ASSERT(expression) do { if(!(expression)) {FATAL_APPLICATION_STATE();} } while(0)
192 #define FATAL_ASSERT1(expression,additional_text) do { if(!(expression)) {FATAL_APPLICATION_STATE1(additional_text);} } while(0)
193
194 /* MS Visual Studio compiler does not support __attribute__() */
195 #ifndef __GNUC__
196 #define __attribute__(x)
197 #endif
198
199 void process_fatal_application_state(const char* sFile, const char* sFunction, int iLine, const char* sAdditionalText) __attribute__((noreturn));
200
201 void generate_stack_trace(const char* i_sFile, const wchar_t* i_wsErrMsg);
202
203 #endif /* FATAL_APPLICATION_STATE */
204
205 /*---------------------------------------------------------------------------
206 * Primitive type definitions
207 *--------------------------------------------------------------------------*/
208
209 #ifdef WIN32
210 typedef __int64 int64;
211 #else
212 #ifndef K_AIX_PLATFORM
213 typedef signed long long int64;
214 #endif
215 #endif
216
217
218 #ifdef K_HPUX_PLATFORM
219 wchar_t* wcsstr (const wchar_t* haystack, const wchar_t* needle);
220 int wprintf (const wchar_t* format, ...);
221 int swprintf (wchar_t* s, size_t maxlen, const wchar_t* format, ...);
222 int vswprintf (wchar_t* s, size_t maxlen, const wchar_t* format, va_list args);
223 int swscanf(const wchar_t *s, const wchar_t *format, ...);
224 int64 atoll(const char *str);
225 #endif
226
227 /*---------------------------------------------------------------------------
228 * Thread type definitions
229 *--------------------------------------------------------------------------*/
230
231 #ifdef WIN32
232 typedef HANDLE K_THREAD_HANDLE;
233 #else
234 typedef pthread_t K_THREAD_HANDLE;
235 #endif
236
237 /*---------------------------------------------------------------------------
238 * Mutex type definitions
239 *--------------------------------------------------------------------------*/
240
241 #ifdef WIN32
242
243 typedef struct {
244 HANDLE m_handle; /* mutex handle */
245
246 CRITICAL_SECTION m_stCriticalSection; /* criticalSection */
247
248 int m_bIsRecursive;
249 } WIN32Mutex;
250
251 typedef WIN32Mutex* K_MUTEX_HANDLE;
252
253 #else
254 typedef pthread_mutex_t* K_MUTEX_HANDLE;
255 #endif
256
257 /*---------------------------------------------------------------------------
258 * Conditional variable type definitions
259 *--------------------------------------------------------------------------*/
260
261 #ifdef WIN32
262 struct K_CondStruct
263 {
264 HANDLE m_hEvent;
265 HANDLE m_hMutex;
266 int m_iSignalAll;
267 int m_iNumWaiting;
268 int m_iSignalled;
269 };
270 typedef struct K_CondStruct K_ConditionalVariable;
271
272 #else
273 typedef pthread_cond_t K_ConditionalVariable;
274 #endif
275
276 /*---------------------------------------------------------------------------
277 * Thread function type definitions
278 *--------------------------------------------------------------------------*/
279
280 /*
281 * Having the function return int breaks compatibility between Windows
282 * and Unix; the function has to return void
283 */
284 /*#ifdef WIN32
285 * typedef int (_stdcall *K_ThreadFunc) (void *vpData);
286 *#else
287 */
288 typedef void (*K_ThreadFunc) (void *vpData);
289 /*
290 *#endif
291 */
292
293
294 /*---------------------------------------------------------------------------
295 * Function: K_CreateThread
296 *
297 * Description:
298 * This thread creation function takes a thread function
299 * and its parameter to create a thread. It also has a Boolean
300 * parameter to indicate if the thread is detached or joinable.
301 * A new thread's handle is returned through the output parameter.
302 *
303 * Input
304 * -----
305 * i_pFunc Function pointer of the thread function
306 * i_pvData The point of the parameter passed to the thread function
307 * i_bIsDetached The thread is detached or not. If detached, then it is
308 * not joinable. (Note: It is not supported on Win32)
309 *
310 * Output
311 * ------
312 * o_pNewThread The Thread handle
313 *
314 * Return value Error code
315 *
316 *--------------------------------------------------------------------------*/
317 int K_CreateThread(K_ThreadFunc i_pFunc,
318 void *i_pvData,
319 int i_bIsDetached,
320 K_THREAD_HANDLE *o_pNewThread);
321
322
323 /*---------------------------------------------------------------------------
324 * Function: K_JoinThread
325 *
326 * Description:
327 * This thread joining function is called when the current thread
328 * waits another thread to terminate.
329 *
330 * Input
331 * -----
332 * i_hThread The thread handle of the to-be-joined thread
333 *
334 * Output
335 * ------
336 * (none)
337 *
338 * Return value Error code
339 *
340 *--------------------------------------------------------------------------*/
341 int K_JoinThread(K_THREAD_HANDLE i_hThread);
342
343
344 /*---------------------------------------------------------------------------
345 * Function: K_GetCurrentThreadId
346 *
347 * Description:
348 * Returns the thread ID of the current thread.
349 *
350 * Input
351 * -----
352 * (none)
353 *
354 * Output
355 * ------
356 * (none)
357 *
358 * Return value The thread ID
359 *
360 *--------------------------------------------------------------------------*/
361
362 int K_GetCurrentThreadId();
363
364
365 /*---------------------------------------------------------------------------
366 * Function: K_CreateMutex
367 *
368 * Description:
369 * The mutex creation function creates a mutex according to the given
370 * mutex type, and returns the mutex handle to the output parameter.
371 *
372 * Input
373 * -----
374 * (none)
375 *
376 * Output
377 * ------
378 * o_phandle the handle pointer to the mutex
379 *
380 * Return value Error Code
381 *
382 *--------------------------------------------------------------------------*/
383
384 int K_CreateMutex( K_MUTEX_HANDLE *o_phandle );
385
386
387 /*---------------------------------------------------------------------------
388 * Function: K_LockMutex
389 *
390 * Description:
391 * K_LockMutex is used to lock the mutex, and K_UnlockMutex is
392 * used to unlock it.
393 *
394 * Input
395 * -----
396 * i_handle the mutex handle
397 *
398 * Output
399 * ------
400 * (none)
401 *
402 * return value Error Code
403 *
404 *--------------------------------------------------------------------------*/
405 int K_LockMutex(K_MUTEX_HANDLE i_handle);
406
407
408 /*---------------------------------------------------------------------------
409 * Function: K_UnlockMutex
410 *
411 * Description:
412 * K_UnlockMutex is used to unlock the lock.
413 *
414 * Input
415 * -----
416 * i_handle the mutex handle
417 *
418 * Output
419 * ------
420 * (none)
421 *
422 * Return value Error Code
423 *
424 *--------------------------------------------------------------------------*/
425 int K_UnlockMutex(K_MUTEX_HANDLE i_handle);
426
427
428 /*---------------------------------------------------------------------------
429 * Function: K_DestroyMutex
430 *
431 * Description:
432 * When a mutex is no longer needed, K_DestroyMutex must be called
433 * to destroy it.
434 *
435 * Input
436 * -----
437 * i_handle the mutex handle
438 *
439 * Output
440 * ------
441 * (none)
442 *
443 * Return value Error Code
444 *
445 *--------------------------------------------------------------------------*/
446
447 int K_DestroyMutex(K_MUTEX_HANDLE i_handle);
448
449
450 /*---------------------------------------------------------------------------
451 *
452 * The following section defines Conditional Variable
453 *
454 * Conditional Variable implements similar functionalities defined
455 * in POSIX thread library. But it only supports conditional variables
456 * inside one process and doesn't support pthread_cond_timedwait().
457 *--------------------------------------------------------------------------*/
458
459
460 /*---------------------------------------------------------------------------
461 * Function: K_InitConditionalVariable
462 *
463 * Description:
464 * This function initializes a conditional variable; Upon successful
465 * completion, the new condition variable is returned via the condition
466 * parameter, and 0 is returned. Otherwise, an error code is returned.
467 *
468 * Input
469 * -----
470 * i_pCond the pointer to the conditional variable which is to be
471 * initialized
472 *
473 * Output
474 * ------
475 * (none)
476 *
477 * Return value Error Code
478 *
479 *--------------------------------------------------------------------------*/
480 int K_InitConditionalVariable (K_ConditionalVariable * i_pCond);
481
482
483
484 /*---------------------------------------------------------------------------
485 * Function: K_DestroyConditionalVariable
486 *
487 * Description:
488 * This function destroys a conditional variable. Upon successful
489 * completion, the condition variable is destroyed, and 0 is returned.
490 * Otherwise, an error code is returned.
491 * After deletion of the condition variable, the condition parameter
492 * is not valid until it is initialized again by a call to the
493 * K_InitConditionalVariable subroutine.
494 *
495 * Input
496 * -----
497 * i_pCond the pointer to the conditional variable which is to be
498 * destroyed
499 *
500 * Output
501 * ------
502 * (none)
503 *
504 * Return value Error Code
505 *
506 *--------------------------------------------------------------------------*/
507
508 int K_DestroyConditionalVariable(K_ConditionalVariable * i_pCond);
509
510
511 /*---------------------------------------------------------------------------
512 * Function: K_WaitConditionalVariable
513 *
514 * Description:
515 * This function is used to block on a condition variable.
516 * They are called with mutex locked by the calling thread or undefined
517 * behaviour will result.
518 *
519 * Input
520 * -----
521 * i_pCond the pointer to the conditional variable
522 * i_handle the companion mutex handle
523 *
524 * Output
525 * ------
526 * (none)
527 *
528 * Return value Error Code
529 *
530 *--------------------------------------------------------------------------*/
531 int K_WaitConditionalVariable(K_ConditionalVariable * i_pCond,
532 K_MUTEX_HANDLE i_handle);
533
534
535 /*---------------------------------------------------------------------------
536 * Function: K_SignalConditionalVariable
537 *
538 * Description:
539 * This function is used to restart one of the threads that are waiting on
540 * the condition variable. If no threads are waiting on it, nothing happens.
541 * If several threads are waiting on it, exactly one is restarted.
542 *
543 * Input
544 * -----
545 * i_pCond the pointer to the conditional variable
546 *
547 * Output
548 * ------
549 * (none)
550 *
551 * Return value Error Code
552 *
553 *--------------------------------------------------------------------------*/
554 int K_SignalConditionalVariable(K_ConditionalVariable * i_pCond);
555
556
557 /*---------------------------------------------------------------------------
558 * Function: K_BroadcastConditionalVariable
559 *
560 * Description:
561 * This function is used to restart all threads that are waiting on
562 * the condition variable.
563 *
564 * Input
565 * -----
566 * i_pCond the pointer to the conditional variable
567 *
568 * Output
569 * ------
570 * (none)
571 *
572 * Return value Error Code
573 *
574 *--------------------------------------------------------------------------*/
575 int K_BroadcastConditionalVariable(K_ConditionalVariable * i_pCond);
576
577
578 /*---------------------------------------------------------------------------
579 * Function: K_Sleep
580 *
581 * Description:
582 * Sleep for a given period in the given milliseconds.
583 *
584 * Input
585 * -----
586 * i_ms milliseconds
587 *
588 * Output
589 * ------
590 * (none)
591 *
592 * Return value (none)
593 *
594 *--------------------------------------------------------------------------*/
595 void K_Sleep(int i_ms);
596
597
598 /*---------------------------------------------------------------------------
599 * Function: K_GetTickCount
600 *
601 * Description:
602 * The K_GetTickCount function retrieves the number of
603 * milliseconds that have elapsed since the system was started.
604 *
605 * Input
606 * -----
607 * (none)
608 *
609 * Output
610 * ------
611 * (none)
612 *
613 * Return value the elasped milliseconds since the system was started
614 *
615 *--------------------------------------------------------------------------*/
616 unsigned int K_GetTickCount();
617
618
619 /*---------------------------------------------------------------------------
620 * Function: K_AdjustClock
621 *
622 * Description:
623 * The K_AdjustClock function immediately adjusts the system clock by
624 * the given number of seconds. A positive number adjusts the system
625 * clock forward; a negative number adjusts the system clock backward.
626 *
627 * Input
628 * -----
629 * i_iAdjustmentInSeconds Number of seconds by which to adjust the
630 * system clock
631 * Output
632 * ------
633 * (none)
634 *
635 * Return value 1 if successful, 0 on error
636 *
637 *--------------------------------------------------------------------------*/
638 int K_AdjustClock( long i_iAdjustmentInSeconds );
639
640
641 /*---------------------------------------------------------------------------
642 * Function: K_IsLittleEndian
643 *
644 * Description:
645 * Checks to see whether this platform uses little endian integer
646 * representation.
647 *
648 * Input
649 * -----
650 * (none)
651 *
652 * Output
653 * ------
654 * (none)
655 *
656 * Return value 1 for little endian
657 *
658 *--------------------------------------------------------------------------*/
659 int K_IsLittleEndian();
660
661
662 /*---------------------------------------------------------------------------
663 * Function: K_FileLength32
664 *
665 * Description:
666 * Gets the size in bytes of the file associated with the given FILE pointer.
667 *
668 * Input
669 * -----
670 * i_fpFile File handle
671 *
672 * Output
673 * ------
674 * (none)
675 *
676 * Return value File size in bytes, or -1L on error
677 *
678 *--------------------------------------------------------------------------*/
679 long K_FileLength32( FILE* i_fpFile );
680
681
682 /*---------------------------------------------------------------------------
683 * Function: K_StringCompareNoCase
684 *
685 * Description:
686 * Compares the two given strings insensitive to case.
687 *
688 * Input
689 * -----
690 * i_sString1 First string
691 * i_sString2 Second string
692 *
693 * Output
694 * ------
695 * (none)
696 *
697 * Return value 0 if identical, -1 if first string is less than second
698 * string, or 1 if first string is greater than second
699 *
700 *--------------------------------------------------------------------------*/
701 int K_StringCompareNoCase( const char* i_sString1, const char* i_sString2 );
702
703
704 /*---------------------------------------------------------------------------
705 * Function: K_StringCompareNoCaseWide
706 *
707 * Description:
708 * Compares the two given wide strings insensitive to case.
709 *
710 * Input
711 * -----
712 * i_wsString1 First wide string
713 * i_wsString2 Second wide string
714 *
715 * Output
716 * ------
717 * (none)
718 *
719 * Return value 0 if identical, -1 if first string is less than second
720 * string, or 1 if first string is greater than second
721 *
722 *--------------------------------------------------------------------------*/
723 int K_StringCompareNoCaseWide( const wchar_t* i_wsString1, const wchar_t* i_wsString2 );
724
725
726 /*---------------------------------------------------------------------------
727 * Function: K_snprintf
728 *
729 * Description:
730 * See the snprintf(3C) man page.
731 *
732 *--------------------------------------------------------------------------*/
733 #ifdef WIN32
734 #define K_snprintf _snprintf
735 #else
736 #define K_snprintf snprintf
737 #endif
738
739
740 /*---------------------------------------------------------------------------
741 * Function: K_snwprintf
742 *
743 * Description:
744 * See the swprintf(3C) man page.
745 *
746 *--------------------------------------------------------------------------*/
747 #ifdef WIN32
748 #define K_snwprintf _snwprintf
749 #else
750 #define K_snwprintf swprintf
751 #endif
752
753 #ifdef WIN32
754 #define K_fseek fseek
755 #define K_ftell ftell
756 #else
757 #define K_fseek fseeko
758 #define K_ftell ftello
759 #endif
760
761
762 /*---------------------------------------------------------------------------
763 * Function: K_CreateDirectory
764 *
765 * Description:
766 * Creates a directory with the given path name.
767 *
768 * Input
769 * -----
770 * i_sDirectoryName Directory name
771 *
772 * Output
773 * ------
774 * (none)
775 *
776 * Return value 0 on success, -1 on failure
777 *
778 *--------------------------------------------------------------------------*/
779 int K_CreateDirectory( const char* i_sDirectoryName );
780
781
782 /*---------------------------------------------------------------------------
783 * Function: K_DeleteFile
784 *
785 * Description:
786 * Deletes the given file.
787 *
788 * Input
789 * -----
790 * i_sFilename Name of file to delete
791 *
792 * Output
793 * ------
794 * (none)
795 *
796 * Return value 0 on success, errno on failure
797 *
798 *--------------------------------------------------------------------------*/
799 int K_DeleteFile( const char* i_sFilename );
800
801
802 /*---------------------------------------------------------------------------
803 * Function: K_ReadFile
804 *
805 * Description:
806 * Reads from the given file and passes the bytes read back to the output
807 * parameter. The caller must deallocate o_ppFileData using free().
808 *
809 * Input
810 * -----
811 * i_sFilename Name of file from which to read
812 *
813 * Output
814 * ------
815 * o_ppFileData Pointer to bytes read
816 *
817 * Return value Number of bytes read on success, -1 on failure
818 *
819 *--------------------------------------------------------------------------*/
820 int K_ReadFile( const char* i_sFilename, unsigned char** o_ppFileData );
821
822
823 /*---------------------------------------------------------------------------
824 * Function: K_ReadFileString
825 *
826 * Description:
827 * Reads from the given file and passes the bytes read back to the output
828 * parameter, appending these bytes with a null terminator. There is no
829 * guarantee that there are no non-text characters in the returned "string".
830 * The caller must deallocate o_ppFileData using free().
831 *
832 * Input
833 * -----
834 * i_sFilename Name of file from which to read
835 *
836 * Output
837 * ------
838 * o_psFileDataString Pointer to bytes read
839 *
840 * Return value Number of bytes read (including null terminator) on
841 * success (0 if file is empty), -1 on failure
842 *
843 *--------------------------------------------------------------------------*/
844 int K_ReadFileString( const char* i_sFilename, char** o_psFileDataString );
845
846
847 /*---------------------------------------------------------------------------
848 * Function: K_WriteFile
849 *
850 * Description:
851 * Writes the given bytes to the given file.
852 *
853 * Input
854 * -----
855 * i_sFilename Name of file to which to write
856 * i_pFileData Bytes to write
857 * i_iFileDataSize Number of bytes to write
858 *
859 * Output
860 * ------
861 * (none)
862 *
863 * Return value 0 on success, errno or -1 (generic error) on failure
864 *
865 *--------------------------------------------------------------------------*/
866 int K_WriteFile( const char* i_sFilename, const unsigned char* i_pFileData, int i_iFileDataSize );
867
868
869 /*---------------------------------------------------------------------------
870 * Function: K_WriteFileString
871 *
872 * Description:
873 * Writes the given null-terminated bytes to the given file. The null
874 * terminator itself is not written to the file.
875 *
876 * Input
877 * -----
878 * i_sFilename Name of file to which to write
879 * i_sFileData Bytes to write
880 *
881 * Output
882 * ------
883 * (none)
884 *
885 * Return value 0 on success, errno or -1 (generic error) on failure
886 *
887 *--------------------------------------------------------------------------*/
888 int K_WriteFileString( const char* i_sFilename, const char* i_sFileData );
889
890
891 /*---------------------------------------------------------------------------
892 * Function: K_FileExists
893 *
894 * Description:
895 * Checks to see whehter the given file exists.
896 *
897 * Input
898 * -----
899 * i_sFilename Name of file to check
900 *
901 * Output
902 * ------
903 * (none)
904 *
905 * Return value 1 if file exists, 0 if not, -1 on failure
906 *
907 *--------------------------------------------------------------------------*/
908 int K_FileExists( const char* i_sFilename );
909
910
911 /*---------------------------------------------------------------------------
912 * Function: K_CopyFile
913 *
914 * Description:
915 * Reads from the given source file and writes these bytes to the given
916 * destination file.
917 *
918 * Input
919 * -----
920 * i_sSrcFilename Name of file from which to read
921 * i_sDestFilename Name of file to which to write
922 *
923 * Output
924 * ------
925 * o_pbFileExists Non-zero if the destination file already exists
926 *
927 * Return value 0 on success, errno or -1 (generic error) on failure
928 *
929 *--------------------------------------------------------------------------*/
930 int K_CopyFile(
931 const char* i_sSrcFilename,
932 const char* i_sDestFilename,
933 int* o_pbFileExists );
934
935
936 /*---------------------------------------------------------------------------
937 * Function: K_GetFilenamesInDirectoryCount
938 *
939 * Description:
940 * Reads the given directory and returns the number of files that it contains.
941 *
942 * Input
943 * -----
944 * i_sDirectoryName Name of directory
945 *
946 * Output
947 * ------
948 * (none)
949 *
950 * Return value Number of files on success, -1 on failure
951 *
952 *--------------------------------------------------------------------------*/
953 int K_GetFilenamesInDirectoryCount( const char* i_sDirectoryName );
954
955
956 /*---------------------------------------------------------------------------
957 * Function: K_GetFilenamesInDirectory
958 *
959 * Description:
960 * Reads the given directory and returns an array of names of files that it
961 * contains. A null pointer appears at the last item in the array. The
962 * caller must deallocate o_pasFilenames by using K_FreeFilenames or by
963 * calling free() for each file name and then calling free() on the array
964 * itself.
965 *
966 * Input
967 * -----
968 * i_sDirectoryName Name of directory
969 *
970 * Output
971 * ------
972 * o_pasFilenames Array of names of files found in this directory
973 *
974 * Return value Number of files on success, -1 on failure
975 *
976 *--------------------------------------------------------------------------*/
977 int K_GetFilenamesInDirectory(
978 const char* i_sDirectoryName,
979 char*** o_pasFilenames );
980
981
982 /*---------------------------------------------------------------------------
983 * Function: K_FreeFilenames
984 *
985 * Description:
986 * Deallocates the memory allocated in a successful call to
987 * K_GetFilenamesInDirectory.
988 *
989 * Input
990 * -----
991 * i_asFilenames Array of names of files
992 *
993 * Output
994 * ------
995 * (none)
996 *
997 * Return value (none)
998 *
999 *--------------------------------------------------------------------------*/
1000 void K_FreeFilenames( char** i_asFilenames );
1001
1002
1003 /*---------------------------------------------------------------------------
1004 * Function: K_AdjustLocalClock
1005 *
1006 * Description:
1007 * The K_AdjustLocalClock function gradually adjusts the system clock by
1008 * the given number of seconds. A positive number adjusts the system
1009 * clock forward; a negative number adjusts the system clock backward.
1010 *
1011 * Input
1012 * -----
1013 * i_iAdjustmentInSeconds Number of seconds by which to adjust the
1014 * system clock
1015 * Output
1016 * ------
1017 * (none)
1018 *
1019 * Return value 1 if successful, 0 on error
1020 *
1021 *--------------------------------------------------------------------------*/
1022 int K_AdjustLocalClock( int i_iNumberOfSeconds );
1023
1024
1025 /*---------------------------------------------------------------------------
1026 * Function: K_SetRootPassword
1027 *
1028 * Description:
1029 * The K_SetRootPassword function sets the password for the root user via
1030 * Pluggable Authentication Module (PAM). This function is interactive.
1031 *
1032 * Input
1033 * -----
1034 * i_sPassword Password to set
1035 *
1036 * Output
1037 * ------
1038 * (none)
1039 *
1040 * Return value 0 if successful, -1 on error
1041 *
1042 *--------------------------------------------------------------------------*/
1043 int K_SetRootPassword( const char* i_sPassword );
1044
1045
1046 /*---------------------------------------------------------------------------
1047 * Function: K_Alarm
1048 *
1049 * Description:
1050 * Calls alarm(2) on Unix in order to cause the operating system to generate
1051 * a SIGALRM signal for this process after the given number of real-time
1052 * seconds. Does nothing on Windows.
1053 *
1054 * Input
1055 * -----
1056 * i_iSeconds Number of seconds after which to generate a SIGALRM
1057 * signal
1058 *
1059 * Output
1060 * ------
1061 * (none)
1062 *
1063 * Return value If a previous alarm request is pending, then it returns
1064 * the number of seconds until this previous request would
1065 * have generated a SIGALRM signal. Otherwise, returns 0.
1066 *
1067 *--------------------------------------------------------------------------*/
1068 unsigned int K_Alarm( unsigned int i_iSeconds );
1069
1070
1071 /*---------------------------------------------------------------------------
1072 * Function: K_GetExtendedVersionFromBase
1073 *
1074 * Description:
1075 * This KMS-specific function prepends the timestamp value to the specified
1076 * base replication schema version and returns this value as an extended
1077 * replication schema version.
1078 *
1079 * Input
1080 * -----
1081 * i_iBaseSchemaVersion Base replication schema version
1082 *
1083 * Output
1084 * ------
1085 * (none)
1086 *
1087 * Return value Extended replication schema version
1088 *
1089 *--------------------------------------------------------------------------*/
1090 unsigned int K_GetExtendedVersionFromBase( unsigned int i_iBaseSchemaVersion );
1091
1092
1093 /*---------------------------------------------------------------------------
1094 * Function: K_ParseTimestampFromExtendedVersion
1095 *
1096 * Description:
1097 * This KMS-specific function parses the timestamp value from the given
1098 * extended replication schema version and returns this timestamp value.
1099 *
1100 * Input
1101 * -----
1102 * i_iExtendedSchemaVersion Extended replication schema version
1103 *
1104 * Output
1105 * ------
1106 * (none)
1107 *
1108 * Return value Timestamp value
1109 *
1110 *--------------------------------------------------------------------------*/
1111 unsigned int K_ParseTimestampFromExtendedVersion(
1112 unsigned int i_iExtendedSchemaVersion );
1113
1114
1115 /*---------------------------------------------------------------------------
1116 * Function: K_ParseBaseFromExtendedVersion
1117 *
1118 * Description:
1119 * This KMS-specific function parses the base replication schema value from
1120 * the given extended replication schema version and returns this base value.
1121 *
1122 * Input
1123 * -----
1124 * i_iExtendedSchemaVersion Extended replication schema version
1125 *
1126 * Output
1127 * ------
1128 * (none)
1129 *
1130 * Return value Base replication schema value
1131 *
1132 *--------------------------------------------------------------------------*/
1133
1134 unsigned int K_ParseBaseFromExtendedVersion(
1135 unsigned int i_iExtendedSchemaVersion );
1136
1137
1138 /*---------------------------------------------------------------------------
1139 * Function: K_System
1140 *
1141 * Description:
1142 * This function is a thread-safe replacement for the unsafe system(3C) call.
1143 * See the popen(3C) man page for more information.
1144 *
1145 * Input
1146 * -----
1147 * i_sCmd Command to execute
1148 *
1149 * Output
1150 * ------
1151 * (none)
1152 *
1153 * Return value Termination status of the command language interpreter
1154 * if successful, -1 on failure
1155 *
1156 *--------------------------------------------------------------------------*/
1157
1158 int K_System( const char *i_sCmd );
1159
1160 #define K_system K_System
1161
1162 #ifdef __cplusplus
1163 }
1164 #endif
1165
1166 #endif
1167
1168