1
#ifndef _psi_src_lib_libpsio_psio_hpp_
2
#define _psi_src_lib_libpsio_psio_hpp_
7
#include <libpsio/config.h>
12
PSIO is an instance of libpsio library. Multiple instances of PSIO are supported.
14
Each instance can be configured using filecfg_kwd().
15
The following example best demonstrates how to configure a PSIO instance Lib:
16
Lib->filecfg_kwd("DEFAULT","NAME",-1,"newwfn") // all modules will set filename prefix to newwfn for all units
17
Lib->filecfg_kwd("DEFAULT","NVOLUME",34,"2") // all modules will stripe unit 34 over 2 volumes
18
Lib->filecfg_kwd("CINTS","VOLUME1",-1,"/scratch1/") // module CINTS will access volume 1 of all units under /scratch
27
/// return 1 if activated
32
set keyword kwd describing some aspect of configuration of PSIO file unit
33
to value kwdval. kwdgrp specifies the keyword group (useful values are: "DEFAULT", "PSI", and the name of
34
the current executable). If unit is set to -1, this keyword will set the default for all units (this keyword
35
can be further overridden for some units). To specify a keyword that works for a specific unit, set unit to the
36
appropriate number between 0 to PSIO_MAXUNIT.
38
PSIO understands the following keywords: "name" (specifies the prefix for the filename,
39
i.e. if name is set to "psi" then unit 35 will be named "psi.35"), "nvolume" (number of files over which
40
to stripe this unit, cannot be greater than PSIO_MAXVOL), "volumeX", where X is a positive integer less than or equal to
41
the value of "nvolume".
43
void filecfg_kwd(const char* kwdgrp, const char* kwd, int unit,
45
/// returns the keyword value. If not defined, returns empty string.
46
const std::string& filecfg_kwd(const char* kwdgrp, const char* kwd,
49
/// open unit. status can be PSIO_OPEN_OLD (if existing file is to be opened) or PSIO_OPEN_NEW if new file should be open
50
void open(unsigned int unit, int status);
51
/// close unit. if keep == 0, will remove the file, else keep it
52
void close(unsigned int unit, int keep);
53
/// sync up the object to the file on disk by closing and opening the file, if necessary
54
void rehash(unsigned int unit);
55
/// return 1 if unit is open
56
int open_check(unsigned int unit);
57
/** Reads data from within a TOC entry from a PSI file.
59
** \param unit = The PSI unit number used to identify the file to all
60
** read and write functions.
61
** \param key = The TOC keyword identifying the desired entry.
62
** \param buffer = The buffer to store the data as it is read.
63
** \param size = The number of bytes to read.
64
** \param start = The entry-relative starting page/offset of the desired data.
65
** \param end = A pointer to the entry-relative page/offset for the next
66
** byte after the end of the read request.
68
void read(unsigned int unit, const char *key, char *buffer, ULI size,
69
psio_address start, psio_address *end);
70
/** Writes data to a TOC entry in a PSI file.
72
** \param unit = The PSI unit number used to identify the file to all read
73
** and write functions.
74
** \param key = The TOC keyword identifying the desired entry.
75
** \param buffer = The buffer from which the data is written.
76
** \param size = The number of bytes to write.
77
** \param start = The entry-relative starting page/offset to write the data.
78
** \param end = A pointer to the entry-relative page/offset for the next
79
** byte after the end of the write request.
81
void write(unsigned int unit, const char *key, char *buffer, ULI size,
82
psio_address start, psio_address *end);
84
void read_entry(unsigned int unit, const char *key, char *buffer, ULI size);
85
void write_entry(unsigned int unit, const char *key, char *buffer, ULI size);
87
/** Central function for all reads and writes on a PSIO unit.
89
** \params unit = The PSI unit number.
90
** \params buffer = The buffer containing the bytes for the read/write event.
91
** \params address = the PSIO global address for the start of the read/write.
92
** \params size = The number of bytes to read/write.
93
** \params = Indicates if the call is to read (0) or write (0) the input data.
97
void rw(unsigned int unit, char *buffer, psio_address address, ULI size,
99
/// Delete all TOC entries after the given key. If a blank key is given, the entire TOC will be wiped.
100
void tocclean(unsigned int unit, const char *key);
101
/// Print the table of contents for the given unit
102
void tocprint(unsigned int unit, FILE *output);
103
/// Scans the TOC for a particular keyword and returns either a pointer to the entry or NULL to the caller.
104
psio_tocentry* tocscan(unsigned int unit, const char *key);
105
/// Write the table of contents for file number 'unit'. NB: This function should NOT call psio_error because the latter calls it!
106
void tocwrite(unsigned int unit);
108
/// Upon catastrophic failure, the library will exit() with this code. The default is 1, but can be overridden.
109
static int _error_exit_code_;
115
typedef std::map<std::string,std::string> KWDMap;
116
/// library configuration is described by a set of keywords
117
KWDMap files_keywords_;
124
/// Library state variable
127
/// grab the filename of unit and strdup into name.
128
void get_filename(unsigned int unit, char **name);
129
/// return the number of volumes over which unit will be striped
130
unsigned int get_numvols(unsigned int unit);
131
/// grab the path to volume of unit and strdup into path.
132
void get_volpath(unsigned int unit, unsigned int volume, char **path);
133
/// return the last TOC entry
134
psio_tocentry* toclast(unsigned int unit);
135
/// Compute the length of the TOC for a given unit using the in-core TOC list.
136
unsigned int toclen(unsigned int unit);
137
/** Read the length of the TOC for a given unit directly from the file.
139
** \param unit = PSI unit number from which to read the toclen.
141
** NB: Note that we do not exit if the read request of the toclen from
142
** the file fails. This is because the request may be to an new file
143
** for which the toclen has not yet been written. (We allow the user
144
** to open files with status PSIO_OPEN_OLD even if they don't exist,
145
** because sometimes you can't know this in advance.)
147
ULI rd_toclen(unsigned int unit);
148
/** Write the length of the TOC for a given unit directly to the file.
150
** \param unit = PSI unit number to which to write the toclen.
154
void wt_toclen(unsigned int unit, ULI toclen);
155
/// Read the table of contents for file number 'unit'.
156
void tocread(unsigned int unit);
161
extern int psiopp_ipv1_config(PSIO *psio_obj);
163
extern PSIO* _default_psio_lib_;
166
#endif /* header guard */
added
removed
src/lib/libpsio/psio.hpp
