| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A store is a fixed-size block of storage, which can be read and perhaps written to. A store is more general than a file: it refers to any type of storage such as devices, files, memory, tasks, etc. Stores can also be representations of other stores, which may be combined and filtered in various ways.
| 8.3 Store Library | An abstract interface to storage systems. |
FIXME: finish
The store library (which is declared in <hurd/store.h>)
implements many different backends which support the store abstraction.
Hurd programs use libstore so that new storage types can be
implemented with minimum impact.
| 8.3.1 Store Arguments | Parsing store command-line arguments. | |
| 8.3.2 Store Management | Creating and manipulating stores. | |
| 8.3.3 Store I/O | Reading and writing data to stores. | |
| 8.3.4 Store Classes | Ready-to-use storage backends. | |
| 8.3.5 Store RPC Encoding | Transferring store descriptors via RPC. |
FIXME: describe startup sequence
The result of parsing a store, which should be enough information to open it, or return the arguments.
This is the structure used to pass args back and forth from
store_argp. result is the resulting parsed result. If
`--store-type' isn't specified, then default_type should be
used as the store type; zero is equivalent to "query".
classes is set of classes used to validate store types and
argument syntax.
This is an argument parser that may be used for parsing a simple command
line specification for stores. The accompanying input parameter must be
a pointer to a struct store_argp_params.
Free all resources used by parsed.
Open the store specified by parsed, and return it in store.
Add the arguments used to create parsed to argz and argz_len.
Make an option string describing parsed, and return it in malloced storage in name.
The following functions provide basic management of stores:
Return a new store in store, which refers to the storage
underlying source. classes is used to select classes
specified by the provider; if zero, store_std_classes is used.
flags is set with store_set_flags, with the exception of
STORE_INACTIVE, which merely indicates that no attempt should be
made to activate an inactive store; if STORE_INACTIVE is not
specified, and the store returned for SOURCE is inactive, an attempt is
made to activate it (failure of which causes an error to be returned).
A reference to source is created (but may be destroyed with
store_close_source).
It is usually better to use a specific store open or create function
such as store_open (see section Store Classes), since they are
tailored to the needs of a specific store. Generally, you should only
use store_create if you are defining your own store class, or you
need options that are not provided by a more specific store creation
function.
If store was created using store_create, remove the
reference to the source from which it was created.
Clean up and deallocate store's underlying stores.
A struct store_run represents a contiguous region in a store's
address range. These are used to designate active portions of a store.
If start is -1, then the region is a hole (it is zero-filled
and doesn't correspond to any real addresses).
Set store's current runs list to (a copy of) runs and num_runs.
Set store's current children to (a copy of) children and num_children (note that just the vector children is copied, not the actual children).
Try to come up with a name for the children in store, combining
the names of each child in a way that could be used to parse them with
store_open_children. This is done heuristically, and so may not
succeed. If a child doesn't have a name, EINVAL is returned.
Sets the name associated with store to a copy of name.
Add flags to store's currently set flags.
Remove flags from store's currently set flags.
Set flags in all children of store, and if successful, add flags to store's flags.
Clear flags in all children of store, and if successful, remove flags from store's flags.
Returns true if store can safely be returned to a user who has accessed it via a node using open_flags, without compromising security.
Return a copy of from in to.
Return a store in store that reflects the blocks in runs and
runs_len from source; source is consumed, but not
runs. Unlike the store_remap_create function, this may
simply modify source and return it.
The following functions allow you to read and modify the contents of a store:
Return a memory object paging on store.
Read amount bytes from store at addr into buf
and len (which follows the usual Mach buffer-return semantics) to
store at addr. addr is in blocks (as defined by
store->block_size). Note that len is in bytes.
Write len bytes from buf to store at addr.
Returns the amount written in amount (in bytes). addr is in
blocks (as defined by store->block_size).
The store library comes with a number of standard store class implementations:
This is a null-terminated vector of the standard store classes
implemented by libstore.
If you are building your own class vectors, the following function may be useful:
Concatenate the store class vectors in cv1 and cv2, and return a new (malloced) vector in concat.
query store This store is a virtual store which queries a filesystem node, and delegates control to an appropriate store class.
Open the file name, and return a new store in store, which
refers to the storage underlying it. classes is used to select
classes specified by the provider; if it is zero, then
store_std_classes is used. flags is set with
store_set_flags. A reference to the open file is created (but
may be destroyed with store_close_source).
typed_open store This store is special in that it doesn't correspond to any specific store functions, rather it provides a way to interpret character strings as specifications for other stores.
Open the store indicated by name, which should consist of a store type name followed by a `:' and any type-specific name, returning the new store in store. classes is used to select classes specified by the type name; if it is zero, store_std_classes is used.
Parse multiple store names in name, and open each individually,
returning all in the vector stores, and the number in
num_stores. The syntax of name is a single non-alphanumeric
separator character, followed by each child store name separated by the
same separator; each child name is `type:name' notation
as parsed by store_typed_open. If every child uses the same
`type:' prefix, then it may be factored out and put before
the child list instead (the two notations are differentiated by whether
or not the first character of name is alphanumeric).
device store This store is a simple wrapper for a microkernel device driver.(10)
Open the device named name, and return the corresponding store in store.
Return a new store in store referring to the microkernel device device. Consumes the device send right.
file store This store reads and writes the contents of a Hurd file.
Open the file name, and return the corresponding store in store.
Return a new store in store referring to the file file.
Unlike store_create, this will always use file I/O, even it would
be possible to be more direct. This may work in more cases, for instance
if the file has holes. Consumes the file send right.
task store This store provides access to the contents of a microkernel task.
Open the task name (name should be the task's pid), and return the corresponding store in store.
Return a new store in store referring to the task task, consuming the task send right.
zero store Reads to this store always return zero-filled buffers, no matter what has been written into it. This store corresponds to the Unix `/dev/zero' device node.
Return a new zero store size bytes long in store.
copy store This store provides a temporary copy of another store. This is useful if you want to provide writable data, but do not wish to modify the underlying store. All changes to a copy store are lost when it is closed.
Open the copy store name (which consists of another store class name, a `:', and a name for the store class to open) and return the corresponding store in store. classes is used to select classes specified by the type name; if it is zero, store_std_classes is used.
Return a new store in store which contains a snapshot of the contents of the store from; from is consumed.
Return a new store in store which contains the memory buffer
buf, of length buf_len. buf must be allocated with
vm_allocate, and will be consumed.
gunzip store This store provides transparent GNU zip decompression of a substore. Unfortunately, this store is currently read-only.
Open the gunzip store name (which consists of another store class name, a `:', and a name for that store class to open), and return the corresponding store in store. classes is used to select classes specified by the type name; if it is zero, store_std_classes is used.
Return a new store in store which contains a snapshot of the uncompressed contents of the store from; from is consumed. block_size is the desired block size of the result.
concat store This class provides a linear concatenation storage mode. It creates a new virtual store which consists of several different substores appended to one another.
This mode is designed to increase storage capacity, so that when one substore is filled, new data is transparently written to the next substore. Concatenation requires robust hardware, since a failure in any single substore will wipe out a large section of the data.
Return a new store that concatenates the stores created by opening all
the individual stores described in name; for the syntax of
name, see store_open_children.
Return a new store in store that concatenates all the stores in stores (num_stores of them). The stores in stores are consumed; that is, they will be freed when this store is freed. The stores array, however, is copied, and so should be freed by the caller.
ileave store This class provides a RAID-0(11) storage mode (also called disk striping). It creates a new virtual store by interleaving the contents of several different substores.
This RAID mode is designed to increase storage performance, since I/O will probably occur in parallel if the substores reside on different physical devices. Interleaving works best with evenly-yoked substores… if the stores are different sizes, some space will be not be used at the end of the larger stores; if the stores are different speeds, then I/O will have to wait for the slowest store; if some stores are not as reliable as others, failures will wipe out every nth storage block, where n is the number of substores.
Return a new store in store that interleaves all the stores in stripes (num_stripes of them) every interleave bytes; interleave must be an integer multiple of each stripe's block size. The stores in stripes are consumed; that is, they will be freed when this store is freed. The stripes array, however, is copied, and so should be freed by the caller.
mvol store This store provides access to multiple volumes using a single-volume device. One use of this store would be to provide a store which consists of multiple floppy disks when there is only a single disk drive. It works by remapping a single linear address range to multiple address ranges, and keeping track of the currently active range. Whenever a request maps to a range that is not active, a callback is made in order to switch to the new range.
This class is not included in store_std_classes, because it requires an application-specific callback.
Return a new store in store that multiplexes multiple physical volumes from phys as one larger virtual volume. swap_vols is a function that will be called whenever reads or writes refer to a block which is not on addressable on the currently active volume. phys is consumed.
remap store This store translates I/O requests into different addresses on a different store.
Return a new store in store that reflects the blocks in runs
and runs_len from source; source is consumed, but
runs is not. Unlike the store_remap function, this
function always operates by creating a new store of type `remap'
which has source as a child, and so may be less efficient than
store_remap for some types of stores.
The store library also provides some functions which help transfer stores between tasks via RPC:
This structure is used to hold the various bits that make up the
representation of a store for transmission via RPC. See
<hurd/hurd_types.h> for an explanation of the encodings for the
various storage types.
Initialize enc. The given vector and sizes will be used for the encoding if they are big enough (otherwise new ones will be automatically allocated).
Deallocate storage used by the fields in enc (but nothing is done with enc itself).
Copy out the parameters from enc into the given variables suitably
for returning from a file_get_storage_info RPC, and deallocate
enc.
Encode store into the given return variables, suitably for
returning from a file_get_storage_info RPC.
Encode store into enc, which should have been prepared with
store_enc_init, or return an error. The contents of enc
may then be returned as the value of file_get_storage_info; if
for some reason this can't be done, store_enc_dealloc may be used
to deallocate the mmemory used by the unsent vectors.
Decode enc, either returning a new store in store, or an
error. classes the mapping from Hurd storage class ids to store
classes; if it is zero, store_std_classes is used. If nothing
else is to be done with enc, its contents may then be freed using
store_enc_dealloc.
Calls the allocate_encoding method in each child store of
store, propagating any errors. If any child does not have such a
method, EOPNOTSUPP is returned.
Calls the encode method in each child store of store, propagating
any errors. If any child does not hae such a method, EOPNOTSUPP
is returned.
Decodes num_children from enc, storing the results into successive positions in children.
Call fun with the vector runs of length num_runs extracted from enc.
Standard encoding used for most data-providing (as opposed to filtering) store classes.
Creation function used by store_std_leaf_decode.
Decodes the standard leaf encoding which is common to various builtin formats, and calls create to actually create the store.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Akihiro Sagawa on June, 15 2005 using texi2html 1.70.