static int DbMpoolFile::open(DbMpool *mp, char *file, u_int32_t flags, int mode, size_t pagesize, DbMpoolFinfo *finfop, DbMpoolFile **mpf);
The DbMpoolFile::open method opens a file in the pool specified by the DbMpool mp, copying the DbMpoolFile pointer representing it into the memory location referenced by mpf.
The file argument is the name of the file to be opened. If file is NULL, a private file is created that cannot be shared with any other process (although it may be shared with other threads).
The flags and mode arguments specify how files will be opened and/or created if they do not already exist. The flags value is specified by logically OR'ing together one or more of the following values:
All files created by the function DbMpoolFile::open are created with mode mode (as described in chmod(2)) and modified by the process' umask value at the time of creation (see umask(2)))). The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.
The pagesize argument is the size, in bytes, of the unit of transfer between the application and the pool, although it is not necessarily the unit of transfer between the pool and the source file.
Files opened in the pool may be further configured based on the finfop argument to DbMpoolFile::open, which is a pointer to a structure of type DB_MPOOL_FINFO). No references to the finfop structure are maintained by Berkeley DB, so it may be discarded when the DbMpoolFile::open function returns. In order to ensure compatibility with future releases of Berkeley DB, all fields of the DB_MPOOL_FINFO structure that are not explicitly set should be initialized to 0 before the first time the structure is used. Do this by declaring the structure external or static, or by calling the C library routine bzero(3) or memset(3).
The fields of the DB_MPOOL_FINFO structure used by DbMpoolFile::open are described below. If finfop is NULL or any of its fields are set to their default value, defaults appropriate for the system are used.
Applications wanting to maintain a shared memory buffer pool across system reboots, where the pool contains pages from files stored on such filesystems, must specify a unique file identifier to the DbMpoolFile::open call and each process opening or registering the file must provide the same unique identifier.
If the fileid field is non-NULL, it must reference a DB_FILE_ID_LEN
length array of bytes that will be used to uniquely identify the file.
This should not be necessary for most applications. Specifically, it is
not necessary if the memory pool is re-instantiated after each system
reboot, the application is using the Berkeley DB access methods instead of
calling the pool functions explicitly, or the files in the memory pool
are stored on filesystems where the file device and inode numbers do not
change across system reboots.
The DbMpoolFile::open method either returns errno or throws an exception that encapsulates an errno on failure, and 0 on success.
The DbMpoolFile::open method may fail and throw an exception for any of the errors specified for the following Berkeley DB and C library functions: DBmemp->pgin(3), DBmemp->pgout(3), abort(3), close(3), dbenv->db_paniccall(3), fcntl(3), fflush(3), fprintf(3), free(3), fstat(3), fsync(3), getenv(3), getpid(3), getuid(3), isdigit(3), DbLog::compare, DbLog::flush, lseek(3), malloc(3), memcmp(3), memcpy(3), memset(3), mmap(3), open(3), pread(3), pstat_getdynamic(3), pwrite(3), read(3), sigfillset(3), sigprocmask(3), stat(3), strerror(3), strlen(3), sysconf(3), time(3), unlink(3), vfprintf(3), vsnprintf(3), and write(3).
In addition, the DbMpoolFile::open method may fail and throw an exception or return errno for the following conditions:
The file has already been entered into the pool, and the pagesize value is not the same as when the file was entered into the pool, or the length of the file is not zero or a multiple of the pagesize.
The DB_RDONLY flag was specified for an in-memory pool.