engine/sqlite/src/os.h
changeset 71 fbd95db6a4e1
parent 69 4a65cc85c4f3
child 72 2e267e7da513
equal deleted inserted replaced
69:4a65cc85c4f3 71:fbd95db6a4e1
     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 #ifndef _SQLITE_OS_H_
       
    21 #define _SQLITE_OS_H_
       
    22 
       
    23 /*
       
    24 ** Figure out if we are dealing with Unix, Windows, or some other
       
    25 ** operating system.  After the following block of preprocess macros,
       
    26 ** all of OS_UNIX, OS_WIN, OS_OS2, and OS_OTHER will defined to either
       
    27 ** 1 or 0.  One of the four will be 1.  The other three will be 0.
       
    28 */
       
    29 
       
    30 #if defined(OS_OTHER)
       
    31 
       
    32 # if OS_OTHER==1
       
    33 #   undef OS_UNIX
       
    34 #   define OS_UNIX 0
       
    35 #   undef OS_WIN
       
    36 #   define OS_WIN 0
       
    37 #   undef OS_OS2
       
    38 #   define OS_OS2 0
       
    39 # else
       
    40 #   undef OS_OTHER
       
    41 # endif
       
    42 #endif
       
    43 #if !defined(OS_UNIX) && !defined(OS_OTHER) && !defined(OS_SYMBIAN)
       
    44 # define OS_OTHER 0
       
    45 # ifndef OS_WIN
       
    46 #   if defined(_WIN32) || defined(WIN32) || defined(__CYGWIN__) || defined(__MINGW32__) || defined(__BORLANDC__)
       
    47 #     define OS_WIN 1
       
    48 #     define OS_UNIX 0
       
    49 #     define OS_OS2 0
       
    50 #   elif defined(__EMX__) || defined(_OS2) || defined(OS2) || defined(_OS2_) || defined(__OS2__)
       
    51 #     define OS_WIN 0
       
    52 #     define OS_UNIX 0
       
    53 #     define OS_OS2 1
       
    54 #   else
       
    55 #     define OS_WIN 0
       
    56 #     define OS_UNIX 1
       
    57 #     define OS_OS2 0
       
    58 #  endif
       
    59 # else
       
    60 #  define OS_UNIX 0
       
    61 #  define OS_OS2 0
       
    62 # endif
       
    63 #else
       
    64 # ifndef OS_WIN
       
    65 #  define OS_WIN 0
       
    66 # endif
       
    67 #endif
       
    68 
       
    69 #ifdef OS_SYMBIAN
       
    70 # define SQLITE_TEMPNAME_SIZE (MAX_PATH+50)
       
    71 #endif
       
    72 
       
    73 
       
    74 /*
       
    75 ** Define the maximum size of a temporary filename
       
    76 */
       
    77 #if OS_WIN
       
    78 # include <windows.h>
       
    79 # define SQLITE_TEMPNAME_SIZE (MAX_PATH+50)
       
    80 #elif OS_OS2
       
    81 # if (__GNUC__ > 3 || __GNUC__ == 3 && __GNUC_MINOR__ >= 3) && defined(OS2_HIGH_MEMORY)
       
    82 #  include <os2safe.h> /* has to be included before os2.h for linking to work */
       
    83 # endif
       
    84 # define INCL_DOSDATETIME
       
    85 # define INCL_DOSFILEMGR
       
    86 # define INCL_DOSERRORS
       
    87 # define INCL_DOSMISC
       
    88 # define INCL_DOSPROCESS
       
    89 # define INCL_DOSMODULEMGR
       
    90 # define INCL_DOSSEMAPHORES
       
    91 # include <os2.h>
       
    92 # define SQLITE_TEMPNAME_SIZE (CCHMAXPATHCOMP)
       
    93 #else
       
    94 #ifndef SQLITE_TEMPNAME_SIZE 
       
    95 	# define SQLITE_TEMPNAME_SIZE 200 
       
    96 #endif
       
    97 #endif
       
    98 
       
    99 /* If the SET_FULLSYNC macro is not defined above, then make it
       
   100 ** a no-op
       
   101 */
       
   102 #ifndef SET_FULLSYNC
       
   103 # define SET_FULLSYNC(x,y)
       
   104 #endif
       
   105 
       
   106 /*
       
   107 ** The default size of a disk sector
       
   108 */
       
   109 #ifndef SQLITE_DEFAULT_SECTOR_SIZE
       
   110 # define SQLITE_DEFAULT_SECTOR_SIZE 512
       
   111 #endif
       
   112 
       
   113 /*
       
   114 ** Temporary files are named starting with this prefix followed by 16 random
       
   115 ** alphanumeric characters, and no file extension. They are stored in the
       
   116 ** OS's standard temporary file directory, and are deleted prior to exit.
       
   117 ** If sqlite is being embedded in another program, you may wish to change the
       
   118 ** prefix to reflect your program's name, so that if your program exits
       
   119 ** prematurely, old temporary files can be easily identified. This can be done
       
   120 ** using -DSQLITE_TEMP_FILE_PREFIX=myprefix_ on the compiler command line.
       
   121 **
       
   122 ** 2006-10-31:  The default prefix used to be "sqlite_".  But then
       
   123 ** Mcafee started using SQLite in their anti-virus product and it
       
   124 ** started putting files with the "sqlite" name in the c:/temp folder.
       
   125 ** This annoyed many windows users.  Those users would then do a 
       
   126 ** Google search for "sqlite", find the telephone numbers of the
       
   127 ** developers and call to wake them up at night and complain.
       
   128 ** For this reason, the default name prefix is changed to be "sqlite" 
       
   129 ** spelled backwards.  So the temp files are still identified, but
       
   130 ** anybody smart enough to figure out the code is also likely smart
       
   131 ** enough to know that calling the developer will not help get rid
       
   132 ** of the file.
       
   133 */
       
   134 #ifndef SQLITE_TEMP_FILE_PREFIX
       
   135 # define SQLITE_TEMP_FILE_PREFIX "etilqs_"
       
   136 #endif
       
   137 
       
   138 /*
       
   139 ** The following values may be passed as the second argument to
       
   140 ** sqlite3OsLock(). The various locks exhibit the following semantics:
       
   141 **
       
   142 ** SHARED:    Any number of processes may hold a SHARED lock simultaneously.
       
   143 ** RESERVED:  A single process may hold a RESERVED lock on a file at
       
   144 **            any time. Other processes may hold and obtain new SHARED locks.
       
   145 ** PENDING:   A single process may hold a PENDING lock on a file at
       
   146 **            any one time. Existing SHARED locks may persist, but no new
       
   147 **            SHARED locks may be obtained by other processes.
       
   148 ** EXCLUSIVE: An EXCLUSIVE lock precludes all other locks.
       
   149 **
       
   150 ** PENDING_LOCK may not be passed directly to sqlite3OsLock(). Instead, a
       
   151 ** process that requests an EXCLUSIVE lock may actually obtain a PENDING
       
   152 ** lock. This can be upgraded to an EXCLUSIVE lock by a subsequent call to
       
   153 ** sqlite3OsLock().
       
   154 */
       
   155 #define NO_LOCK         0
       
   156 #define SHARED_LOCK     1
       
   157 #define RESERVED_LOCK   2
       
   158 #define PENDING_LOCK    3
       
   159 #define EXCLUSIVE_LOCK  4
       
   160 
       
   161 /*
       
   162 ** File Locking Notes:  (Mostly about windows but also some info for Unix)
       
   163 **
       
   164 ** We cannot use LockFileEx() or UnlockFileEx() on Win95/98/ME because
       
   165 ** those functions are not available.  So we use only LockFile() and
       
   166 ** UnlockFile().
       
   167 **
       
   168 ** LockFile() prevents not just writing but also reading by other processes.
       
   169 ** A SHARED_LOCK is obtained by locking a single randomly-chosen 
       
   170 ** byte out of a specific range of bytes. The lock byte is obtained at 
       
   171 ** random so two separate readers can probably access the file at the 
       
   172 ** same time, unless they are unlucky and choose the same lock byte.
       
   173 ** An EXCLUSIVE_LOCK is obtained by locking all bytes in the range.
       
   174 ** There can only be one writer.  A RESERVED_LOCK is obtained by locking
       
   175 ** a single byte of the file that is designated as the reserved lock byte.
       
   176 ** A PENDING_LOCK is obtained by locking a designated byte different from
       
   177 ** the RESERVED_LOCK byte.
       
   178 **
       
   179 ** On WinNT/2K/XP systems, LockFileEx() and UnlockFileEx() are available,
       
   180 ** which means we can use reader/writer locks.  When reader/writer locks
       
   181 ** are used, the lock is placed on the same range of bytes that is used
       
   182 ** for probabilistic locking in Win95/98/ME.  Hence, the locking scheme
       
   183 ** will support two or more Win95 readers or two or more WinNT readers.
       
   184 ** But a single Win95 reader will lock out all WinNT readers and a single
       
   185 ** WinNT reader will lock out all other Win95 readers.
       
   186 **
       
   187 ** The following #defines specify the range of bytes used for locking.
       
   188 ** SHARED_SIZE is the number of bytes available in the pool from which
       
   189 ** a random byte is selected for a shared lock.  The pool of bytes for
       
   190 ** shared locks begins at SHARED_FIRST. 
       
   191 **
       
   192 ** These #defines are available in sqlite_aux.h so that adaptors for
       
   193 ** connecting SQLite to other operating systems can use the same byte
       
   194 ** ranges for locking.  In particular, the same locking strategy and
       
   195 ** byte ranges are used for Unix.  This leaves open the possiblity of having
       
   196 ** clients on win95, winNT, and unix all talking to the same shared file
       
   197 ** and all locking correctly.  To do so would require that samba (or whatever
       
   198 ** tool is being used for file sharing) implements locks correctly between
       
   199 ** windows and unix.  I'm guessing that isn't likely to happen, but by
       
   200 ** using the same locking range we are at least open to the possibility.
       
   201 **
       
   202 ** Locking in windows is manditory.  For this reason, we cannot store
       
   203 ** actual data in the bytes used for locking.  The pager never allocates
       
   204 ** the pages involved in locking therefore.  SHARED_SIZE is selected so
       
   205 ** that all locks will fit on a single page even at the minimum page size.
       
   206 ** PENDING_BYTE defines the beginning of the locks.  By default PENDING_BYTE
       
   207 ** is set high so that we don't have to allocate an unused page except
       
   208 ** for very large databases.  But one should test the page skipping logic 
       
   209 ** by setting PENDING_BYTE low and running the entire regression suite.
       
   210 **
       
   211 ** Changing the value of PENDING_BYTE results in a subtly incompatible
       
   212 ** file format.  Depending on how it is changed, you might not notice
       
   213 ** the incompatibility right away, even running a full regression test.
       
   214 ** The default location of PENDING_BYTE is the first byte past the
       
   215 ** 1GB boundary.
       
   216 **
       
   217 */
       
   218 #ifndef SQLITE_TEST
       
   219 #define PENDING_BYTE      0x40000000  /* First byte past the 1GB boundary */
       
   220 #else
       
   221 extern unsigned int sqlite3_pending_byte;
       
   222 #define PENDING_BYTE sqlite3_pending_byte
       
   223 #endif
       
   224 
       
   225 #define RESERVED_BYTE     (PENDING_BYTE+1)
       
   226 #define SHARED_FIRST      (PENDING_BYTE+2)
       
   227 #define SHARED_SIZE       510
       
   228 
       
   229 /* 
       
   230 ** Functions for accessing sqlite3_file methods 
       
   231 */
       
   232 int sqlite3OsClose(sqlite3_file*);
       
   233 int sqlite3OsRead(sqlite3_file*, void*, int amt, i64 offset);
       
   234 int sqlite3OsWrite(sqlite3_file*, const void*, int amt, i64 offset);
       
   235 int sqlite3OsTruncate(sqlite3_file*, i64 size);
       
   236 int sqlite3OsSync(sqlite3_file*, int);
       
   237 int sqlite3OsFileSize(sqlite3_file*, i64 *pSize);
       
   238 int sqlite3OsLock(sqlite3_file*, int);
       
   239 int sqlite3OsUnlock(sqlite3_file*, int);
       
   240 int sqlite3OsCheckReservedLock(sqlite3_file *id);
       
   241 int sqlite3OsFileControl(sqlite3_file*,int,void*);
       
   242 int sqlite3OsSectorSize(sqlite3_file *id);
       
   243 int sqlite3OsDeviceCharacteristics(sqlite3_file *id);
       
   244 
       
   245 /* 
       
   246 ** Functions for accessing sqlite3_vfs methods 
       
   247 */
       
   248 int sqlite3OsOpen(sqlite3_vfs *, const char *, sqlite3_file*, int, int *);
       
   249 int sqlite3OsDelete(sqlite3_vfs *, const char *, int);
       
   250 int sqlite3OsAccess(sqlite3_vfs *, const char *, int);
       
   251 int sqlite3OsGetTempname(sqlite3_vfs *, int, char *);
       
   252 int sqlite3OsFullPathname(sqlite3_vfs *, const char *, int, char *);
       
   253 void *sqlite3OsDlOpen(sqlite3_vfs *, const char *);
       
   254 void sqlite3OsDlError(sqlite3_vfs *, int, char *);
       
   255 void *sqlite3OsDlSym(sqlite3_vfs *, void *, const char *);
       
   256 void sqlite3OsDlClose(sqlite3_vfs *, void *);
       
   257 int sqlite3OsRandomness(sqlite3_vfs *, int, char *);
       
   258 int sqlite3OsSleep(sqlite3_vfs *, int);
       
   259 int sqlite3OsCurrentTime(sqlite3_vfs *, double*);
       
   260 
       
   261 /*
       
   262 ** Convenience functions for opening and closing files using 
       
   263 ** sqlite3_malloc() to obtain space for the file-handle structure.
       
   264 */
       
   265 int sqlite3OsOpenMalloc(sqlite3_vfs *, const char *, sqlite3_file **, int,int*);
       
   266 int sqlite3OsCloseFree(sqlite3_file *);
       
   267 
       
   268 /*
       
   269 ** Each OS-specific backend defines an instance of the following
       
   270 ** structure for returning a pointer to its sqlite3_vfs.  If OS_OTHER
       
   271 ** is defined (meaning that the application-defined OS interface layer
       
   272 ** is used) then there is no default VFS.   The application must
       
   273 ** register one or more VFS structures using sqlite3_vfs_register()
       
   274 ** before attempting to use SQLite.
       
   275 */
       
   276 #if OS_UNIX || OS_WIN || OS_OS2 ||  OS_SYMBIAN
       
   277 sqlite3_vfs *sqlite3OsDefaultVfs(void);
       
   278 #else
       
   279 # define sqlite3OsDefaultVfs(X) 0
       
   280 #endif
       
   281 
       
   282  int winDelete(
       
   283   sqlite3_vfs *pVfs,          /* Not used on win32 */
       
   284   const char *zFilename,      /* Name of file to delete */
       
   285   int syncDir                 /* Not used on win32 */
       
   286 );
       
   287 
       
   288  int winAccess(
       
   289   sqlite3_vfs *pVfs,         /* Not used on win32 */
       
   290   const char *zFilename,     /* Name of file to check */
       
   291   int flags                  /* Type of test to make on this file */
       
   292 );
       
   293 
       
   294  int winGetTempname(sqlite3_vfs *pVfs, int nBuf, char *zBuf);
       
   295 
       
   296  int winFullPathname(
       
   297   sqlite3_vfs *pVfs,            /* Pointer to vfs object */
       
   298   const char *zRelative,        /* Possibly relative input path */
       
   299   int nFull,                    /* Size of output buffer in bytes */
       
   300   char *zFull                   /* Output buffer */
       
   301 );
       
   302 
       
   303  int winRandomness(sqlite3_vfs *pVfs, int nBuf, char *zBuf);
       
   304 
       
   305  int winClose(sqlite3_file *id);
       
   306 
       
   307  int winRead(
       
   308   sqlite3_file *id,          /* File to read from */
       
   309   void *pBuf,                /* Write content into this buffer */
       
   310   int amt,                   /* Number of bytes to read */
       
   311   sqlite3_int64 offset       /* Begin reading at this offset */
       
   312 );
       
   313 
       
   314  int winWrite(
       
   315   sqlite3_file *id,         /* File to write into */
       
   316   const void *pBuf,         /* The bytes to be written */
       
   317   int amt,                  /* Number of bytes to write */
       
   318   sqlite3_int64 offset      /* Offset into the file to begin writing at */
       
   319 );
       
   320 
       
   321  int winTruncate(sqlite3_file *id, sqlite3_int64 nByte);
       
   322 
       
   323  int winSync(sqlite3_file *id, int flags);
       
   324 
       
   325  int symbianFileSize(sqlite3_file *id, sqlite3_int64 *pSize);
       
   326 
       
   327  int winLock(sqlite3_file *id, int locktype);
       
   328 
       
   329  int winCheckReservedLock(sqlite3_file *id);
       
   330 
       
   331  int winUnlock(sqlite3_file *id, int locktype);
       
   332 
       
   333  int symbianFileControl(sqlite3_file *id, int op, void *pArg);
       
   334 
       
   335  int winSectorSize(sqlite3_file *id);
       
   336 
       
   337  int winDeviceCharacteristics(sqlite3_file *id);
       
   338 
       
   339  int winOpen(
       
   340   sqlite3_vfs *pVfs,        /* Not used */
       
   341   const char *zName,        /* Name of the file (UTF-8) */
       
   342   sqlite3_file *id,         /* Write the SQLite file handle here */
       
   343   int flags,                /* Open mode flags */
       
   344   int *pOutFlags            /* Status return flags */
       
   345 );
       
   346  int winFullPathname(
       
   347   sqlite3_vfs *pVfs,            /* Pointer to vfs object */
       
   348   const char *zRelative,        /* Possibly relative input path */
       
   349   int nFull,                    /* Size of output buffer in bytes */
       
   350   char *zFull                   /* Output buffer */
       
   351 );
       
   352  int winSleep(sqlite3_vfs *pVfs, int microsec);
       
   353  int winCurrentTime(sqlite3_vfs *pVfs, double *prNow);
       
   354 
       
   355  int winFileSize(sqlite3_file *id, sqlite3_int64 *pSize);
       
   356 
       
   357  int winFileControl(sqlite3_file *id, int op, void *pArg);
       
   358 
       
   359 #endif /* _SQLITE_OS_H_ */