1 /*===========================================================================
2 *
3 *                            PUBLIC DOMAIN NOTICE
4 *               National Center for Biotechnology Information
5 *
6 *  This software/database is a "United States Government Work" under the
7 *  terms of the United States Copyright Act.  It was written as part of
8 *  the author's official duties as a United States Government employee and
9 *  thus cannot be copyrighted.  This software/database is freely available
10 *  to the public for use. The National Library of Medicine and the U.S.
11 *  Government have not placed any restriction on its use or reproduction.
12 *
13 *  Although all reasonable efforts have been taken to ensure the accuracy
14 *  and reliability of the software and data, the NLM and the U.S.
15 *  Government do not and cannot warrant the performance or results that
16 *  may be obtained by using this software or data. The NLM and the U.S.
17 *  Government disclaim all warranties, express or implied, including
18 *  warranties of performance, merchantability or fitness for any particular
19 *  purpose.
20 *
21 *  Please cite the author in any work or product based on this material.
22 *
23 * ===========================================================================
24 *
25 */
26 
27 #ifndef _h_kfs_lockfile_
28 #define _h_kfs_lockfile_
29 
30 #ifndef _h_kfs_extern_
31 #include <kfs/extern.h>
32 #endif
33 
34 #ifndef _h_kfs_defs_
35 #include <kfs/defs.h>
36 #endif
37 
38 #include <stdarg.h>
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 
45 /*--------------------------------------------------------------------------
46  * forwards
47  */
48 struct KFile;
49 struct KDirectory;
50 
51 
52 /*--------------------------------------------------------------------------
53  * KLockFile
54  *  a mutual exclusion lock on a file
55  *  the lock is acquired upon creation
56  *  and released upon destruction
57  *
58  * NB - only guaranteed to work when used from a single host
59  */
60 typedef struct KLockFile KLockFile;
61 
62 
63 /* AddRef
64  * Release
65  */
66 KFS_EXTERN rc_t CC KLockFileAddRef ( const KLockFile *self );
67 KFS_EXTERN rc_t CC KLockFileRelease ( const KLockFile *self );
68 
69 
70 
71 /*--------------------------------------------------------------------------
72  * KDirectory
73  *  interface extensions
74  */
75 
76 
77 /* CreateLockFile
78  *  attempts to create a KLockFile
79  *
80  *  "lock" [ OUT ] - return parameter for newly created lock file
81  *
82  *  "path" [ IN ] - NUL terminated string in directory-native
83  *  character set denoting lock file
84  */
85 KFS_EXTERN rc_t CC KDirectoryCreateLockFile ( struct KDirectory *self,
86     KLockFile **lock, const char *path, ... );
87 KFS_EXTERN rc_t CC KDirectoryVCreateLockFile ( struct KDirectory *self,
88     KLockFile **lock, const char *path, va_list args );
89 
90 
91 /* CreateExclusiveAccessFile
92  *  opens a file with exclusive write access
93  *
94  *  "f" [ OUT ] - return parameter for newly opened file
95  *
96  *  "update" [ IN ] - if true, open in read/write mode
97  *  otherwise, open in write-only mode
98  *
99  *  "access" [ IN ] - standard Unix access mode, e.g. 0664
100  *
101  *  "mode" [ IN ] - a creation mode ( see explanation above ).
102  *
103  *  "path" [ IN ] - NUL terminated string in directory-native
104  *  character set denoting target file
105  */
106 KFS_EXTERN rc_t CC KDirectoryCreateExclusiveAccessFile ( struct KDirectory *self, struct KFile **f,
107     bool update, uint32_t access, KCreateMode mode, const char *path, ... );
108 KFS_EXTERN rc_t CC KDirectoryVCreateExclusiveAccessFile ( struct KDirectory *self, struct KFile **f,
109     bool update, uint32_t access, KCreateMode mode, const char *path, va_list args );
110 
111 
112 #ifdef __cplusplus
113 }
114 #endif
115 
116 #endif /* _h_kfs_lockfile_ */
117