1 /*

     2 ** 2001 September 16

     3 **

     4 ** The author disclaims copyright to this source code.  In place of

     5 ** a legal notice, here is a blessing:

     6 **

     7 **    May you do good and not evil.

     8 **    May you find forgiveness for yourself and forgive others.

     9 **    May you share freely, never taking more than you give.

    10 **

    11 ******************************************************************************

    12 **

    13 ** This header file (together with is companion C source-code file

    14 ** "os.c") attempt to abstract the underlying operating system so that

    15 ** the SQLite library will work on both POSIX and windows systems.

    16 **

    17 ** This header file is #include-ed by sqliteInt.h and thus ends up

    18 ** being included by every source file.

    19 **

    20 ** $Id: os.h,v 1.105 2008/06/26 10:41:19 danielk1977 Exp $

    21 */

    22 #ifndef _SQLITE_OS_H_

    23 #define _SQLITE_OS_H_

    24 

    25 /*

    26 ** Figure out if we are dealing with Unix, Windows, or some other

    27 ** operating system.  After the following block of preprocess macros,

    28 ** all of SQLITE_OS_UNIX, SQLITE_OS_WIN, SQLITE_OS_OS2, and SQLITE_OS_OTHER 

    29 ** will defined to either 1 or 0.  One of the four will be 1.  The other 

    30 ** three will be 0.

    31 */

    32 #if defined(SQLITE_OS_OTHER)

    33 # if SQLITE_OS_OTHER==1

    34 #   undef SQLITE_OS_UNIX

    35 #   define SQLITE_OS_UNIX 0

    36 #   undef SQLITE_OS_WIN

    37 #   define SQLITE_OS_WIN 0

    38 #   undef SQLITE_OS_OS2

    39 #   define SQLITE_OS_OS2 0

    40 # else

    41 #   undef SQLITE_OS_OTHER

    42 # endif

    43 #endif

    44 #if !defined(SQLITE_OS_UNIX) && !defined(SQLITE_OS_OTHER)

    45 # define SQLITE_OS_OTHER 0

    46 # ifndef SQLITE_OS_WIN

    47 #   if defined(_WIN32) || defined(WIN32) || defined(__CYGWIN__) || defined(__MINGW32__) || defined(__BORLANDC__)

    48 #     define SQLITE_OS_WIN 1

    49 #     define SQLITE_OS_UNIX 0

    50 #     define SQLITE_OS_OS2 0

    51 #   elif defined(__EMX__) || defined(_OS2) || defined(OS2) || defined(_OS2_) || defined(__OS2__)

    52 #     define SQLITE_OS_WIN 0

    53 #     define SQLITE_OS_UNIX 0

    54 #     define SQLITE_OS_OS2 1

    55 #   else

    56 #     define SQLITE_OS_WIN 0

    57 #     define SQLITE_OS_UNIX 1

    58 #     define SQLITE_OS_OS2 0

    59 #  endif

    60 # else

    61 #  define SQLITE_OS_UNIX 0

    62 #  define SQLITE_OS_OS2 0

    63 # endif

    64 #else

    65 # ifndef SQLITE_OS_WIN

    66 #  define SQLITE_OS_WIN 0

    67 # endif

    68 #endif

    69 

    70 /*

    71 ** Determine if we are dealing with WindowsCE - which has a much

    72 ** reduced API.

    73 */

    74 #if defined(_WIN32_WCE)

    75 # define SQLITE_OS_WINCE 1

    76 #else

    77 # define SQLITE_OS_WINCE 0

    78 #endif

    79 

    80 

    81 /*

    82 ** Define the maximum size of a temporary filename

    83 */

    84 #if SQLITE_OS_WIN

    85 # include <windows.h>

    86 # define SQLITE_TEMPNAME_SIZE (MAX_PATH+50)

    87 #elif SQLITE_OS_OS2

    88 # if (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ >= 3) && defined(OS2_HIGH_MEMORY)

    89 #  include <os2safe.h> /* has to be included before os2.h for linking to work */

    90 # endif

    91 # define INCL_DOSDATETIME

    92 # define INCL_DOSFILEMGR

    93 # define INCL_DOSERRORS

    94 # define INCL_DOSMISC

    95 # define INCL_DOSPROCESS

    96 # define INCL_DOSMODULEMGR

    97 # define INCL_DOSSEMAPHORES

    98 # include <os2.h>

    99 # include <uconv.h>

   100 # define SQLITE_TEMPNAME_SIZE (CCHMAXPATHCOMP)

   101 #else

   102 # define SQLITE_TEMPNAME_SIZE 200

   103 #endif

   104 

   105 /* If the SET_FULLSYNC macro is not defined above, then make it

   106 ** a no-op

   107 */

   108 #ifndef SET_FULLSYNC

   109 # define SET_FULLSYNC(x,y)

   110 #endif

   111 

   112 /*

   113 ** The default size of a disk sector

   114 */

   115 #ifndef SQLITE_DEFAULT_SECTOR_SIZE

   116 # define SQLITE_DEFAULT_SECTOR_SIZE 512

   117 #endif

   118 

   119 /*

   120 ** Temporary files are named starting with this prefix followed by 16 random

   121 ** alphanumeric characters, and no file extension. They are stored in the

   122 ** OS's standard temporary file directory, and are deleted prior to exit.

   123 ** If sqlite is being embedded in another program, you may wish to change the

   124 ** prefix to reflect your program's name, so that if your program exits

   125 ** prematurely, old temporary files can be easily identified. This can be done

   126 ** using -DSQLITE_TEMP_FILE_PREFIX=myprefix_ on the compiler command line.

   127 **

   128 ** 2006-10-31:  The default prefix used to be "sqlite_".  But then

   129 ** Mcafee started using SQLite in their anti-virus product and it

   130 ** started putting files with the "sqlite" name in the c:/temp folder.

   131 ** This annoyed many windows users.  Those users would then do a 

   132 ** Google search for "sqlite", find the telephone numbers of the

   133 ** developers and call to wake them up at night and complain.

   134 ** For this reason, the default name prefix is changed to be "sqlite" 

   135 ** spelled backwards.  So the temp files are still identified, but

   136 ** anybody smart enough to figure out the code is also likely smart

   137 ** enough to know that calling the developer will not help get rid

   138 ** of the file.

   139 */

   140 #ifndef SQLITE_TEMP_FILE_PREFIX

   141 # define SQLITE_TEMP_FILE_PREFIX "etilqs_"

   142 #endif

   143 

   144 /*

   145 ** The following values may be passed as the second argument to

   146 ** sqlite3OsLock(). The various locks exhibit the following semantics:

   147 **

   148 ** SHARED:    Any number of processes may hold a SHARED lock simultaneously.

   149 ** RESERVED:  A single process may hold a RESERVED lock on a file at

   150 **            any time. Other processes may hold and obtain new SHARED locks.

   151 ** PENDING:   A single process may hold a PENDING lock on a file at

   152 **            any one time. Existing SHARED locks may persist, but no new

   153 **            SHARED locks may be obtained by other processes.

   154 ** EXCLUSIVE: An EXCLUSIVE lock precludes all other locks.

   155 **

   156 ** PENDING_LOCK may not be passed directly to sqlite3OsLock(). Instead, a

   157 ** process that requests an EXCLUSIVE lock may actually obtain a PENDING

   158 ** lock. This can be upgraded to an EXCLUSIVE lock by a subsequent call to

   159 ** sqlite3OsLock().

   160 */

   161 #define NO_LOCK         0

   162 #define SHARED_LOCK     1

   163 #define RESERVED_LOCK   2

   164 #define PENDING_LOCK    3

   165 #define EXCLUSIVE_LOCK  4

   166 

   167 /*

   168 ** File Locking Notes:  (Mostly about windows but also some info for Unix)

   169 **

   170 ** We cannot use LockFileEx() or UnlockFileEx() on Win95/98/ME because

   171 ** those functions are not available.  So we use only LockFile() and

   172 ** UnlockFile().

   173 **

   174 ** LockFile() prevents not just writing but also reading by other processes.

   175 ** A SHARED_LOCK is obtained by locking a single randomly-chosen 

   176 ** byte out of a specific range of bytes. The lock byte is obtained at 

   177 ** random so two separate readers can probably access the file at the 

   178 ** same time, unless they are unlucky and choose the same lock byte.

   179 ** An EXCLUSIVE_LOCK is obtained by locking all bytes in the range.

   180 ** There can only be one writer.  A RESERVED_LOCK is obtained by locking

   181 ** a single byte of the file that is designated as the reserved lock byte.

   182 ** A PENDING_LOCK is obtained by locking a designated byte different from

   183 ** the RESERVED_LOCK byte.

   184 **

   185 ** On WinNT/2K/XP systems, LockFileEx() and UnlockFileEx() are available,

   186 ** which means we can use reader/writer locks.  When reader/writer locks

   187 ** are used, the lock is placed on the same range of bytes that is used

   188 ** for probabilistic locking in Win95/98/ME.  Hence, the locking scheme

   189 ** will support two or more Win95 readers or two or more WinNT readers.

   190 ** But a single Win95 reader will lock out all WinNT readers and a single

   191 ** WinNT reader will lock out all other Win95 readers.

   192 **

   193 ** The following #defines specify the range of bytes used for locking.

   194 ** SHARED_SIZE is the number of bytes available in the pool from which

   195 ** a random byte is selected for a shared lock.  The pool of bytes for

   196 ** shared locks begins at SHARED_FIRST. 

   197 **

   198 ** These #defines are available in sqlite_aux.h so that adaptors for

   199 ** connecting SQLite to other operating systems can use the same byte

   200 ** ranges for locking.  In particular, the same locking strategy and

   201 ** byte ranges are used for Unix.  This leaves open the possiblity of having

   202 ** clients on win95, winNT, and unix all talking to the same shared file

   203 ** and all locking correctly.  To do so would require that samba (or whatever

   204 ** tool is being used for file sharing) implements locks correctly between

   205 ** windows and unix.  I'm guessing that isn't likely to happen, but by

   206 ** using the same locking range we are at least open to the possibility.

   207 **

   208 ** Locking in windows is manditory.  For this reason, we cannot store

   209 ** actual data in the bytes used for locking.  The pager never allocates

   210 ** the pages involved in locking therefore.  SHARED_SIZE is selected so

   211 ** that all locks will fit on a single page even at the minimum page size.

   212 ** PENDING_BYTE defines the beginning of the locks.  By default PENDING_BYTE

   213 ** is set high so that we don't have to allocate an unused page except

   214 ** for very large databases.  But one should test the page skipping logic 

   215 ** by setting PENDING_BYTE low and running the entire regression suite.

   216 **

   217 ** Changing the value of PENDING_BYTE results in a subtly incompatible

   218 ** file format.  Depending on how it is changed, you might not notice

   219 ** the incompatibility right away, even running a full regression test.

   220 ** The default location of PENDING_BYTE is the first byte past the

   221 ** 1GB boundary.

   222 **

   223 */

   224 #ifndef SQLITE_TEST

   225 #define PENDING_BYTE      0x40000000  /* First byte past the 1GB boundary */

   226 #else

   227 extern unsigned int sqlite3_pending_byte;

   228 #define PENDING_BYTE sqlite3_pending_byte

   229 #endif

   230 

   231 #define RESERVED_BYTE     (PENDING_BYTE+1)

   232 #define SHARED_FIRST      (PENDING_BYTE+2)

   233 #define SHARED_SIZE       510

   234 

   235 /* 

   236 ** Functions for accessing sqlite3_file methods 

   237 */

   238 int sqlite3OsClose(sqlite3_file*);

   239 int sqlite3OsRead(sqlite3_file*, void*, int amt, i64 offset);

   240 int sqlite3OsWrite(sqlite3_file*, const void*, int amt, i64 offset);

   241 int sqlite3OsTruncate(sqlite3_file*, i64 size);

   242 int sqlite3OsSync(sqlite3_file*, int);

   243 int sqlite3OsFileSize(sqlite3_file*, i64 *pSize);

   244 int sqlite3OsLock(sqlite3_file*, int);

   245 int sqlite3OsUnlock(sqlite3_file*, int);

   246 int sqlite3OsCheckReservedLock(sqlite3_file *id, int *pResOut);

   247 int sqlite3OsFileControl(sqlite3_file*,int,void*);

   248 int sqlite3OsSectorSize(sqlite3_file *id);

   249 int sqlite3OsDeviceCharacteristics(sqlite3_file *id);

   250 

   251 /* 

   252 ** Functions for accessing sqlite3_vfs methods 

   253 */

   254 int sqlite3OsOpen(sqlite3_vfs *, const char *, sqlite3_file*, int, int *);

   255 int sqlite3OsDelete(sqlite3_vfs *, const char *, int);

   256 int sqlite3OsAccess(sqlite3_vfs *, const char *, int, int *pResOut);

   257 int sqlite3OsFullPathname(sqlite3_vfs *, const char *, int, char *);

   258 #ifndef SQLITE_OMIT_LOAD_EXTENSION

   259 void *sqlite3OsDlOpen(sqlite3_vfs *, const char *);

   260 void sqlite3OsDlError(sqlite3_vfs *, int, char *);

   261 void *sqlite3OsDlSym(sqlite3_vfs *, void *, const char *);

   262 void sqlite3OsDlClose(sqlite3_vfs *, void *);

   263 #endif /* SQLITE_OMIT_LOAD_EXTENSION */

   264 int sqlite3OsRandomness(sqlite3_vfs *, int, char *);

   265 int sqlite3OsSleep(sqlite3_vfs *, int);

   266 int sqlite3OsCurrentTime(sqlite3_vfs *, double*);

   267 

   268 /*

   269 ** Convenience functions for opening and closing files using 

   270 ** sqlite3_malloc() to obtain space for the file-handle structure.

   271 */

   272 int sqlite3OsOpenMalloc(sqlite3_vfs *, const char *, sqlite3_file **, int,int*);

   273 int sqlite3OsCloseFree(sqlite3_file *);

   274 

   275 #endif /* _SQLITE_OS_H_ */