1 |
/* Store I/O |
/* Store I/O |
2 |
|
|
3 |
Copyright (C) 1995,96,97,98,99,2001 Free Software Foundation, Inc. |
Copyright (C) 1995,96,97,98,99,2001,02 Free Software Foundation, Inc. |
4 |
Written by Miles Bader <miles@gnu.org> |
Written by Miles Bader <miles@gnu.org> |
5 |
This file is part of the GNU Hurd. |
This file is part of the GNU Hurd. |
6 |
|
|
204 |
error_t (*map) (const struct store *store, vm_prot_t prot, mach_port_t *memobj); |
error_t (*map) (const struct store *store, vm_prot_t prot, mach_port_t *memobj); |
205 |
}; |
}; |
206 |
|
|
207 |
/* Return a new store in STORE, which refers to the storage underlying SOURCE. |
/* Return a new store in STORE, which refers to the storage underlying |
208 |
CLASSES is used to select classes specified by the provider; if it is 0, |
SOURCE. CLASSES is as if passed to store_find_class, which see. FLAGS |
209 |
STORE_STD_CLASSES is used. FLAGS is set with store_set_flags, with the |
is set with store_set_flags, with the exception of STORE_INACTIVE, which |
210 |
exception of STORE_INACTIVE, which merely indicates that no attempt should |
merely indicates that no attempt should be made to activate an inactive |
211 |
be made to activate an inactive store; if STORE_INACTIVE is not specified, |
store; if STORE_INACTIVE is not specified, and the store returned for |
212 |
and the store returned for SOURCE is inactive, an attempt is made to |
SOURCE is inactive, an attempt is made to activate it (failure of which |
213 |
activate it (failure of which causes an error to be returned). A reference |
causes an error to be returned). A reference to SOURCE is created (but |
214 |
to SOURCE is created (but may be destroyed with store_close_source). */ |
may be destroyed with store_close_source). */ |
215 |
error_t store_create (file_t source, int flags, |
error_t store_create (file_t source, int flags, |
216 |
const struct store_class *const *classes, |
const struct store_class *const *classes, |
217 |
struct store **store); |
struct store **store); |
219 |
void store_free (struct store *store); |
void store_free (struct store *store); |
220 |
|
|
221 |
/* Open the file NAME, and return a new store in STORE, which refers to the |
/* Open the file NAME, and return a new store in STORE, which refers to the |
222 |
storage underlying it. CLASSES is used to select classes specified by the |
storage underlying it. CLASSES is as if passed to store_find_class, |
223 |
provider; if it is 0, STORE_STD_CLASSES is used. FLAGS is set with |
which see. FLAGS is set with store_set_flags. A reference to the open |
224 |
store_set_flags. A reference to the open file is created (but may be |
file is created (but may be destroyed with store_close_source). */ |
|
destroyed with store_close_source). */ |
|
225 |
error_t store_open (const char *name, int flags, |
error_t store_open (const char *name, int flags, |
226 |
const struct store_class *const *classes, |
const struct store_class *const *classes, |
227 |
struct store **store); |
struct store **store); |
345 |
error_t store_part_create (struct store *source, int index, int flags, |
error_t store_part_create (struct store *source, int index, int flags, |
346 |
struct store **store); |
struct store **store); |
347 |
|
|
348 |
/* Open the part NAME. NAME consists of a partition number, a ':', a another |
/* Open the part NAME. NAME consists of a partition number, a ':', a |
349 |
store class name, a ':' and a name for to by passed to the store class. |
another store class name, a ':' and a name for to by passed to the |
350 |
E.g. "2:device:hd0" would open the second partition on a DEVICE store |
store class. E.g. "2:device:hd0" would open the second partition |
351 |
named "hd0". FLAGS indicate how to open the store. CLASSES is used to |
on a DEVICE store named "hd0". FLAGS indicate how to open the |
352 |
select classes specified by the type NAME; if it is 0, STORE_STD_CLASSES |
store. CLASSES is as if passed to store_find_class, which see. |
353 |
is used. The new store is returned in *STORE. */ |
The new store is returned in *STORE. */ |
354 |
error_t store_part_open (const char *name, int flags, |
error_t store_part_open (const char *name, int flags, |
355 |
const struct store_class *const *classes, |
const struct store_class *const *classes, |
356 |
struct store **store); |
struct store **store); |
400 |
const struct store_run *runs, size_t num_runs, |
const struct store_run *runs, size_t num_runs, |
401 |
struct store **store); |
struct store **store); |
402 |
|
|
|
/* 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-alpha-numeric 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 types of notation are differentiated by whether the |
|
|
first character of name is alpha-numeric or not). */ |
|
|
error_t store_open_children (const char *name, int flags, |
|
|
const struct store_class *const *classes, |
|
|
struct store ***stores, size_t *num_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 0, STORE_STD_CLASSES is used. */ |
|
|
error_t store_typed_open (const char *name, int flags, |
|
|
const struct store_class *const *classes, |
|
|
struct store **store); |
|
|
|
|
|
/* Similar to store_typed_open, but NAME must be in URL format, |
|
|
i.e. a class name followed by a ':' and any type-specific name. |
|
|
A leading ':' or no ':' at all is invalid syntax. */ |
|
|
error_t store_url_open (const char *name, int flags, |
|
|
const struct store_class *const *classes, |
|
|
struct store **store); |
|
|
|
|
403 |
/* Return a new store of type "unknown" that holds a copy of the |
/* Return a new store of type "unknown" that holds a copy of the |
404 |
given encoding. The name of the store is taken from ENC->data. |
given encoding. The name of the store is taken from ENC->data. |
405 |
Future calls to store_encode/store_return will produce exactly |
Future calls to store_encode/store_return will produce exactly |
439 |
error_t store_remap_create (struct store *source, |
error_t store_remap_create (struct store *source, |
440 |
const struct store_run *runs, size_t num_runs, |
const struct store_run *runs, size_t num_runs, |
441 |
int flags, struct store **store); |
int flags, struct store **store); |
442 |
|
|
443 |
/* Return a new store in STORE which contains a snapshot of the contents of |
/* Return a new store in STORE which contains a snapshot of the contents of |
444 |
the store FROM; FROM is consumed. */ |
the store FROM; FROM is consumed. */ |
445 |
error_t store_copy_create (struct store *from, int flags, struct store **store); |
error_t store_copy_create (struct store *from, int flags, struct store **store); |
446 |
|
|
447 |
/* Open the copy store NAME -- which consists of another store-class name, a |
/* Open the copy store NAME -- which consists of another store-class |
448 |
':', and a name for that store class to open -- and return the |
name, a ':', and a name for that store class to open -- and return |
449 |
corresponding store in STORE. CLASSES is used to select classes specified |
the corresponding store in STORE. CLASSES is as if passed to |
450 |
by the type name; if it is 0, STORE_STD_CLASSES is used. */ |
store_find_class, which see. */ |
451 |
error_t store_copy_open (const char *name, int flags, |
error_t store_copy_open (const char *name, int flags, |
452 |
const struct store_class *const *classes, |
const struct store_class *const *classes, |
453 |
struct store **store); |
struct store **store); |
463 |
error_t store_gunzip_create (struct store *from, int flags, |
error_t store_gunzip_create (struct store *from, int flags, |
464 |
struct store **store); |
struct store **store); |
465 |
|
|
466 |
/* Open the gunzip NAME -- which consists of another store-class name, a ':', |
/* Open the gunzip NAME -- which consists of another store-class name, a |
467 |
and a name for that store class to open -- and return the corresponding |
':', and a name for that store class to open -- and return the |
468 |
store in STORE. CLASSES is used to select classes specified by the type |
corresponding store in STORE. CLASSES is as if passed to |
469 |
name; if it is 0, STORE_STD_CLASSES is used. */ |
store_find_class, which see. */ |
470 |
error_t store_gunzip_open (const char *name, int flags, |
error_t store_gunzip_open (const char *name, int flags, |
471 |
const struct store_class *const *classes, |
const struct store_class *const *classes, |
472 |
struct store **store); |
struct store **store); |
479 |
|
|
480 |
/* Open the bunzip2 NAME -- which consists of another store-class name, a ':', |
/* Open the bunzip2 NAME -- which consists of another store-class name, a ':', |
481 |
and a name for that store class to open -- and return the corresponding |
and a name for that store class to open -- and return the corresponding |
482 |
store in STORE. CLASSES is used to select classes specified by the type |
store in STORE. CLASSES is as if passed to store_find_class, which see. */ |
|
name; if it is 0, STORE_STD_CLASSES is used. */ |
|
483 |
error_t store_bunzip2_open (const char *name, int flags, |
error_t store_bunzip2_open (const char *name, int flags, |
484 |
const struct store_class *const *classes, |
const struct store_class *const *classes, |
485 |
struct store **store); |
struct store **store); |
494 |
int flags, |
int flags, |
495 |
struct store **store); |
struct store **store); |
496 |
|
|
497 |
/* Standard store classes implemented by libstore. */ |
/* Opening stores from a standard set of store classes. |
498 |
extern const struct store_class *const store_std_classes[]; |
|
499 |
|
These first two functions underlie the following functions, and |
500 |
|
other functions such as store_open taking a CLASSES argument that |
501 |
|
can be null. The standard set of classes to be searched when that |
502 |
|
argument is null includes all the `const struct store_class *' |
503 |
|
pointers found in the `store_std_classes' section of the executable |
504 |
|
and all loaded shared objects; store_find_class searches that set |
505 |
|
for the named class. The store_typed_open and store_url_open |
506 |
|
functions also try store_module_find_class, but only if the |
507 |
|
function has already been linked in; it's always available in the |
508 |
|
shared library, and available for static linking with |
509 |
|
-lstore_module -ldl. |
510 |
|
|
511 |
|
The macro STORE_STD_CLASS produces a reference in the `store_std_classes' |
512 |
|
section, so that linking in a module containing that definition will add |
513 |
|
the referenced class to the standard search list. In the shared library, |
514 |
|
the various standard classes are included this way. In the static |
515 |
|
library, only the pseudo classes like `query' and `typed' will normally |
516 |
|
be linked in (via referenced to store_open and so forth); to force |
517 |
|
specific store type modules to be linked in, you must specify an |
518 |
|
`-lstore_CLASS' option for each individual class to be statically linked. |
519 |
|
*/ |
520 |
|
|
521 |
|
/* Find a store class by name. CLNAME_END points to the character |
522 |
|
after the class name NAME points to; if null, then NAME is just the |
523 |
|
null-terminated class name. */ |
524 |
|
const struct store_class * |
525 |
|
store_find_class (const char *name, |
526 |
|
const char *clname_end, |
527 |
|
const struct store_class *const *classes); |
528 |
|
|
529 |
|
/* This is the underlying function that tries to load a module to |
530 |
|
define the store type called NAME. On success, returns zero |
531 |
|
and sets *CLASSP to the descriptor found. Returns ENOENT if |
532 |
|
there is no such module, or other error codes if there is a |
533 |
|
module but it does not load correctly. */ |
534 |
|
error_t store_module_find_class (const char *name, |
535 |
|
const char *clname_end, |
536 |
|
const struct store_class **classp); |
537 |
|
|
538 |
|
|
539 |
|
/* Open the store indicated by NAME, which should consist of a store |
540 |
|
type name followed by a ':' and any type-specific name, returning the |
541 |
|
new store in STORE. CLASSES is as if passed to store_find_class, |
542 |
|
which see. */ |
543 |
|
error_t store_typed_open (const char *name, int flags, |
544 |
|
const struct store_class *const *classes, |
545 |
|
struct store **store); |
546 |
|
|
547 |
|
/* Similar to store_typed_open, but NAME must be in URL format, i.e. a |
548 |
|
class name followed by a ':' and any type-specific name. A leading ':' |
549 |
|
or no ':' at all is invalid syntax. (See store_module_open, below.) */ |
550 |
|
error_t store_url_open (const char *name, int flags, |
551 |
|
const struct store_class *const *classes, |
552 |
|
struct store **store); |
553 |
|
|
554 |
|
/* This attempts to decode a standard-form STORAGE_NETWORK encoding whose |
555 |
|
encoded name is in URL format, by finding the store type indicated in |
556 |
|
the URL (as for store_url_open) and that type's decode function. */ |
557 |
|
error_t store_url_decode (struct store_enc *enc, |
558 |
|
const struct store_class *const *classes, |
559 |
|
struct store **store); |
560 |
|
|
561 |
|
|
562 |
|
/* Similar to store_typed_open, but the store type's code is found |
563 |
|
dynamically rather than statically in CLASSES. A shared object name |
564 |
|
for `dlopen' and symbol names for `dlsym' are derived from the type |
565 |
|
name and used to find the `struct store_class' for the named type. |
566 |
|
(CLASSES is used only by the type's own open function, e.g. if that |
567 |
|
type accepts a child-store syntax in its name.) |
568 |
|
|
569 |
|
In fact, when this code is linked in (always in the shared library, |
570 |
|
only with `-lstore_module -ldl -lstore' for static linking), all |
571 |
|
the functions documented as using STORE_STD_CLASSES will also |
572 |
|
check for loadable modules if the type name is not found statically. */ |
573 |
|
error_t store_module_open (const char *name, int flags, |
574 |
|
const struct store_class *const *classes, |
575 |
|
struct store **store); |
576 |
|
|
577 |
|
|
578 |
|
/* This attempts to find a module that can decode ENC. If no such |
579 |
|
module can be found it returns ENOENT. Otherwise it returns |
580 |
|
the result of the loaded store type's `decode' function. */ |
581 |
|
error_t store_module_decode (struct store_enc *enc, |
582 |
|
const struct store_class *const *classes, |
583 |
|
struct store **store); |
584 |
|
|
585 |
|
/* Parse multiple store names in NAME, and open each individually, returning |
586 |
|
all in the vector STORES, and the number in NUM_STORES. The syntax of |
587 |
|
NAME is a single non-alpha-numeric separator character, followed by each |
588 |
|
child store name separated by the same separator; each child name is |
589 |
|
TYPE:NAME notation as parsed by store_typed_open. If every child uses the |
590 |
|
same TYPE: prefix, then it may be factored out and put before the child |
591 |
|
list instead (the two types of notation are differentiated by whether the |
592 |
|
first character of name is alpha-numeric or not). */ |
593 |
|
error_t store_open_children (const char *name, int flags, |
594 |
|
const struct store_class *const *classes, |
595 |
|
struct store ***stores, size_t *num_stores); |
596 |
|
|
597 |
|
|
598 |
|
/* Standard store classes implemented by libstore. */ |
599 |
extern const struct store_class store_device_class; |
extern const struct store_class store_device_class; |
600 |
extern const struct store_class store_part_class; |
extern const struct store_class store_part_class; |
601 |
extern const struct store_class store_file_class; |
extern const struct store_class store_file_class; |
612 |
extern const struct store_class store_bunzip2_class; |
extern const struct store_class store_bunzip2_class; |
613 |
extern const struct store_class store_typed_open_class; |
extern const struct store_class store_typed_open_class; |
614 |
extern const struct store_class store_url_open_class; |
extern const struct store_class store_url_open_class; |
615 |
|
extern const struct store_class store_module_open_class; |
616 |
extern const struct store_class store_unknown_class; |
extern const struct store_class store_unknown_class; |
617 |
|
|
618 |
/* The following are not included in STORE_STD_CLASSES. */ |
/* The following are not included in STORE_STD_CLASSES. */ |
619 |
extern const struct store_class store_mvol_class; |
extern const struct store_class store_mvol_class; |
620 |
|
|
621 |
/* Concatenates the store class vectors in CV1 and CV2, and returns a new |
#define STORE_STD_CLASS(name) \ |
622 |
(malloced) vector in CONCAT. */ |
static const struct store_class *const store_std_classes_##name[] \ |
623 |
error_t store_concat_class_vectors (struct store_class **cv1, |
__attribute__ ((unused, section ("store_std_classes"))) \ |
624 |
struct store_class **cv2, |
= { &store_##name##_class } |
625 |
struct store_class ***concat); |
|
626 |
|
extern const struct store_class *const __start_store_std_classes[]; |
627 |
|
extern const struct store_class *const __stop_store_std_classes[]; |
628 |
|
|
629 |
/* Used to hold the various bits that make up the representation of a store |
/* Used to hold the various bits that make up the representation of a store |
630 |
for transmission via rpc. See <hurd/hurd_types.h> for an explanation of |
for transmission via rpc. See <hurd/hurd_types.h> for an explanation of |
688 |
used by the unsent vectors. */ |
used by the unsent vectors. */ |
689 |
error_t store_encode (const struct store *store, struct store_enc *enc); |
error_t store_encode (const struct store *store, struct store_enc *enc); |
690 |
|
|
691 |
/* Decode ENC, either returning a new store in STORE, or an error. CLASSES |
/* Decode ENC, either returning a new store in STORE, or an error. |
692 |
defines the mapping from hurd storage class ids to store classes; if it is |
CLASSES is as if passed to store_find_class, which see. If nothing |
693 |
0, STORE_STD_CLASSES is used. If nothing else is to be done with ENC, its |
else is to be done with ENC, its contents may then be freed using |
694 |
contents may then be freed using store_enc_dealloc. */ |
store_enc_dealloc. */ |
695 |
error_t store_decode (struct store_enc *enc, |
error_t store_decode (struct store_enc *enc, |
696 |
const struct store_class *const *classes, |
const struct store_class *const *classes, |
697 |
struct store **store); |
struct store **store); |