summaryrefslogtreecommitdiffstats
path: root/tests/pkg.test
blob: 7d818d438957150e77105897124f85a54739a85f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
# -*- tcl -*-
# Commands covered:  pkg
#
# This file contains a collection of tests for one or more of the Tcl
# built-in commands.  Sourcing this file into Tcl runs the tests and
# generates output for errors.  No output means no errors were found.
#
# Copyright (c) 1995-1996 Sun Microsystems, Inc.
# Copyright (c) 1998-1999 by Scriptics Corporation.
#
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.

if {[lsearch [namespace children] ::tcltest] == -1} {
    package require tcltest 2
    namespace import -force ::tcltest::*
}

# Do all this in a slave interp to avoid garbaging the
# package list
set i [interp create]
interp eval $i [list set argv $argv]
interp eval $i [list package require tcltest 2]
interp eval $i [list namespace import -force ::tcltest::*]
interp eval $i {

package forget {*}[package names]
set oldPkgUnknown [package unknown]
package unknown {}
set oldPath $auto_path
set auto_path ""

test pkg-1.1 {Tcl_PkgProvide procedure} {
    package forget t
    package provide t 2.3
} {}
test pkg-1.2 {Tcl_PkgProvide procedure} {
    package forget t
    package provide t 2.3
    list [catch {package provide t 2.2} msg] $msg
} {1 {conflicting versions provided for package "t": 2.3, then 2.2}}
test pkg-1.3 {Tcl_PkgProvide procedure} {
    package forget t
    package provide t 2.3
    list [catch {package provide t 2.4} msg] $msg
} {1 {conflicting versions provided for package "t": 2.3, then 2.4}}
test pkg-1.4 {Tcl_PkgProvide procedure} {
    package forget t
    package provide t 2.3
    list [catch {package provide t 3.3} msg] $msg
} {1 {conflicting versions provided for package "t": 2.3, then 3.3}}
test pkg-1.5 {Tcl_PkgProvide procedure} {
    package forget t
    package provide t 2.3
    package provide t 2.3
} {}

test pkg-1.6 {Tcl_PkgProvide procedure} {
    package forget t
    package provide t 2.3a1
} {}

set n 0
foreach v {
    2.3k1 2a3a2 2ab3 2.a4 2.b4 2b.4 2a.4 2ba4 2a4b1
    2b4a1 2b3b2
} {
    test pkg-1.7.$n {Tcl_PkgProvide procedure} {
	package forget t
	list [catch {package provide t $v} msg] $msg
    } [list 1 "expected version number but got \"$v\""]
    incr n
}

test pkg-2.1 {Tcl_PkgRequire procedure, picking best version} {
    package forget t
    foreach i {1.4 3.4 2.3 2.4 2.2} {
	package ifneeded t $i "set x $i; package provide t $i"
    }
    set x xxx
    package require t
    set x
} {3.4}
test pkg-2.2 {Tcl_PkgRequire procedure, picking best version} {
    package forget t
    foreach i {1.4 3.4 2.3 2.4 2.2 3.5 3.2} {
	package ifneeded t $i "set x $i; package provide t $i"
    }
    set x xxx
    package require t
    set x
} {3.5}
test pkg-2.3 {Tcl_PkgRequire procedure, picking best version} {
    package forget t
    foreach i {3.5 2.1 2.3} {
	package ifneeded t $i "set x $i; package provide t $i"
    }
    set x xxx
    package require t 2.2
    set x
} {2.3}
test pkg-2.4 {Tcl_PkgRequire procedure, picking best version} {
    package forget t
    foreach i {1.4 3.4 2.3 2.4 2.2} {
	package ifneeded t $i "set x $i; package provide t $i"
    }
    set x xxx
    package require -exact t 2.3
    set x
} {2.3}
test pkg-2.5 {Tcl_PkgRequire procedure, picking best version} {
    package forget t
    foreach i {1.4 3.4 2.3 2.4 2.2} {
	package ifneeded t $i "set x $i; package provide t $i"
    }
    set x xxx
    package require t 2.1
    set x
} {2.4}
test pkg-2.6 {Tcl_PkgRequire procedure, can't find suitable version} {
    package forget t
    package unknown {}
    foreach i {1.4 3.4 2.3 2.4 2.2} {
	package ifneeded t $i "set x $i"
    }
    list [catch {package require t 2.5} msg] $msg
} {1 {can't find package t 2.5}}
test pkg-2.7 {Tcl_PkgRequire procedure, can't find suitable version} {
    package forget t
    package unknown {}
    foreach i {1.4 3.4 2.3 2.4 2.2} {
	package ifneeded t $i "set x $i"
    }
    list [catch {package require t 4.1} msg] $msg
} {1 {can't find package t 4.1}}
test pkg-2.8 {Tcl_PkgRequire procedure, can't find suitable version} {
    package forget t
    package unknown {}
    foreach i {1.4 3.4 2.3 2.4 2.2} {
	package ifneeded t $i "set x $i"
    }
    list [catch {package require -exact t 1.3} msg] $msg
} {1 {can't find package t exactly 1.3}}
test pkg-2.9 {Tcl_PkgRequire procedure, can't find suitable version} {
    package forget t
    package unknown {}
    list [catch {package require t} msg] $msg
} {1 {can't find package t}}
test pkg-2.10 {Tcl_PkgRequire procedure, error in ifneeded script} -body {
    package forget t
    package ifneeded t 2.1 {package provide t 2.1; error "ifneeded test"}
    list [catch {package require t 2.1} msg] $msg $::errorInfo
} -match glob -result {1 {ifneeded test} {ifneeded test
    while executing
"error "ifneeded test""
    ("package ifneeded*" script)
    invoked from within
"package require t 2.1"}}
test pkg-2.11 {Tcl_PkgRequire procedure, ifneeded script doesn't provide package} -body {
    package forget t
    package ifneeded t 2.1 "set x invoked"
    set x xxx
    list [catch {package require t 2.1} msg] $msg $x
} -match glob -result {1 * invoked}
test pkg-2.12 {Tcl_PkgRequire procedure, self-deleting script} {
    package forget t
    package ifneeded t 1.2 "package forget t; set x 1.2; package provide t 1.2"
    set x xxx
    package require t 1.2
    set x
} {1.2}
test pkg-2.13 {Tcl_PkgRequire procedure, "package unknown" support} {
    proc pkgUnknown args {
	# args = name requirement
	# requirement = v-v (for exact version)
	global x
	set x $args
	package provide [lindex $args 0] [lindex [split [lindex $args 1] -] 0]
    }
    package forget t
    foreach i {1.4 3.4 2.3 2.4 2.2} {
	package ifneeded t $i "set x $i"
    }
    package unknown pkgUnknown
    set x xxx
    package require -exact t 1.5
    package unknown {}
    set x
} {t 1.5-1.5}
test pkg-2.14 {Tcl_PkgRequire procedure, "package unknown" support} {
    proc pkgUnknown args {
	package ifneeded t 1.2 "set x loaded; package provide t 1.2"
    }
    package forget t
    package unknown pkgUnknown
    set x xxx
    set result [list [package require t] $x]
    package unknown {}
    set result
} {1.2 loaded}
test pkg-2.15 {Tcl_PkgRequire procedure, "package unknown" support} {
    proc pkgUnknown args {
	global x
	set x $args
	package provide [lindex $args 0] 2.0
    }
    package forget {a b}
    package unknown pkgUnknown
    set x xxx
    package require {a b}
    package unknown {}
    set x
} {{a b} 0-}
test pkg-2.16 {Tcl_PkgRequire procedure, "package unknown" error} {
    proc pkgUnknown args {
	error "testing package unknown"
    }
    package forget t 
    package unknown pkgUnknown
    set result [list [catch {package require t} msg] $msg $::errorInfo]
    package unknown {}
    set result
} {1 {testing package unknown} {testing package unknown
    while executing
"error "testing package unknown""
    (procedure "pkgUnknown" line 2)
    invoked from within
"pkgUnknown t 0-"
    ("package unknown" script)
    invoked from within
"package require t"}}
test pkg-2.17 {Tcl_PkgRequire procedure, "package unknown" doesn't load package} {
    proc pkgUnknown args {
	global x
	set x $args
    }
    package forget t
    foreach i {1.4 3.4 2.3 2.4 2.2} {
	package ifneeded t $i "set x $i"
    }
    package unknown pkgUnknown
    set x xxx
    set result [list [catch {package require -exact t 1.5} msg] $msg $x]
    package unknown {}
    set result
} {1 {can't find package t exactly 1.5} {t 1.5-1.5}}
test pkg-2.18 {Tcl_PkgRequire procedure, version checks} {
    package forget t
    package provide t 2.3
    package require t
} {2.3}
test pkg-2.19 {Tcl_PkgRequire procedure, version checks} {
    package forget t
    package provide t 2.3
    package require t 2.1
} {2.3}
test pkg-2.20 {Tcl_PkgRequire procedure, version checks} {
    package forget t
    package provide t 2.3
    package require t 2.3
} {2.3}
test pkg-2.21 {Tcl_PkgRequire procedure, version checks} {
    package forget t
    package provide t 2.3
    list [catch {package require t 2.4} msg] $msg
} {1 {version conflict for package "t": have 2.3, need 2.4}}
test pkg-2.22 {Tcl_PkgRequire procedure, version checks} {
    package forget t
    package provide t 2.3
    list [catch {package require t 1.2} msg] $msg
} {1 {version conflict for package "t": have 2.3, need 1.2}}
test pkg-2.23 {Tcl_PkgRequire procedure, version checks} {
    package forget t
    package provide t 2.3
    package require -exact t 2.3
} {2.3}
test pkg-2.24 {Tcl_PkgRequire procedure, version checks} {
    package forget t
    package provide t 2.3
    list [catch {package require -exact t 2.2} msg] $msg
} {1 {version conflict for package "t": have 2.3, need exactly 2.2}}
test pkg-2.25 {Tcl_PkgRequire procedure, error in ifneeded script} -body {
    package forget t
    package ifneeded t 2.1 {package provide t 2.1; error "ifneeded test" EI}
    list [catch {package require t 2.1} msg] $msg $::errorInfo
} -match glob -result {1 {ifneeded test} {EI
    ("package ifneeded*" script)
    invoked from within
"package require t 2.1"}}
test pkg-2.26 {Tcl_PkgRequire procedure, error in ifneeded script} -body {
    package forget t
    package ifneeded t 2.1 {package provide t 2.1; foreach x 1 {error "ifneeded test" EI}}
    list [catch {package require t 2.1} msg] $msg $::errorInfo
} -match glob -result {1 {ifneeded test} {EI
    ("foreach" body line 1)
    invoked from within
"foreach x 1 {error "ifneeded test" EI}"
    ("package ifneeded*" script)
    invoked from within
"package require t 2.1"}}
test pkg-2.27 {Tcl_PkgRequire: circular dependency} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {package require foo 1}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob -result {circular package dependency:*}
test pkg-2.28 {Tcl_PkgRequire: circular dependency} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {package require foo 2}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob -result {circular package dependency:*}
test pkg-2.29 {Tcl_PkgRequire: circular dependency} -setup {
    package forget foo
    package forget bar
} -body {
    package ifneeded foo 1 {package require bar 1; package provide foo 1}
    package ifneeded bar 1 {package require foo 1; package provide bar 1}
    package require foo 1
} -cleanup {
    package forget foo
    package forget bar
} -returnCodes error -match glob -result {circular package dependency:*}
test pkg-2.30 {Tcl_PkgRequire: circular dependency} -setup {
    package forget foo
    package forget bar
} -body {
    package ifneeded foo 1 {package require bar 1; package provide foo 1}
    package ifneeded foo 2 {package provide foo 2}
    package ifneeded bar 1 {package require foo 2; package provide bar 1}
    package require foo 1
} -cleanup {
    package forget foo
    package forget bar
} -returnCodes error -match glob -result {circular package dependency:*}
test pkg-2.31 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {package provide foo 1; error foo}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob -result foo
test pkg-2.32 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {package provide foo 1; error foo}
    catch {package require foo 1}
    package provide foo
} -cleanup {
    package forget foo
} -result {}
test pkg-2.33 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {package provide foo 2}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob -result {attempt to provide package * failed:*}
test pkg-2.34 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {package provide foo 1.1}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob -result {attempt to provide package * failed:*}
test pkg-2.34.1 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1.1 {package provide foo 1}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob -result {attempt to provide package * failed:*}
test pkg-2.34.2 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1.1 {package provide foo 1}
    package require foo 1.1
} -cleanup {
    package forget foo
} -returnCodes error -match glob -result {attempt to provide package * failed:*}
test pkg-2.35 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob -result {attempt to provide package * failed:*}
test pkg-2.35.1 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {break}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob \
-result {attempt to provide package * failed: bad return code:*}
test pkg-2.36 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {continue}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob \
-result {attempt to provide package * failed: bad return code:*}
test pkg-2.37 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {return}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob \
-result {attempt to provide package * failed: bad return code:*}
test pkg-2.38 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
} -body {
    package ifneeded foo 1 {return -level 0 -code 10}
    package require foo 1
} -cleanup {
    package forget foo
} -returnCodes error -match glob \
-result {attempt to provide package * failed: bad return code:*}
test pkg-2.39 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
    set saveUnknown [package unknown]
    package unknown {package provide foo 2 ;#}
} -body {
    package require foo 1
} -cleanup {
    package forget foo
    package unknown $saveUnknown
} -returnCodes error -match glob -result *
test pkg-2.40 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
    set saveUnknown [package unknown]
    package unknown {break ;#}
} -body {
    package require foo 1
} -cleanup {
    package forget foo
    package unknown $saveUnknown
} -returnCodes error -match glob -result {bad return code:*}
test pkg-2.41 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
    set saveUnknown [package unknown]
    package unknown {continue ;#}
} -body {
    package require foo 1
} -cleanup {
    package forget foo
    package unknown $saveUnknown
} -returnCodes error -match glob -result {bad return code:*}
test pkg-2.42 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
    set saveUnknown [package unknown]
    package unknown {return ;#}
} -body {
    package require foo 1
} -cleanup {
    package forget foo
    package unknown $saveUnknown
} -returnCodes error -match glob -result {bad return code:*}
test pkg-2.43 {Tcl_PkgRequire: consistent return values (1162286)} -setup {
    package forget foo
    set saveUnknown [package unknown]
    package unknown {return -level 0 -code 10 ;#}
} -body {
    package require foo 1
} -cleanup {
    package forget foo
    package unknown $saveUnknown
} -returnCodes error -match glob -result {bad return code:*}
test pkg-2.44 {Tcl_PkgRequire: exact version matching (1578344)} -setup {
    package provide demo 1.2.3
} -body {
    package require -exact demo 1.2
} -cleanup {
    package forget demo
} -returnCodes error -result {version conflict for package "demo": have 1.2.3, need exactly 1.2}


test pkg-2.50 {Tcl_PkgRequire procedure, picking best stable version} {
    package forget t
    foreach i {1.4 3.4 4.0a1 2.3 2.4 2.2} {
	package ifneeded t $i "set x $i; package provide t $i"
    }
    set x xxx
    package require t
    set x
} {3.4}

test pkg-2.51 {Tcl_PkgRequire procedure, picking best stable version} {
    package forget t
    foreach i {1.2b1 1.2 1.3a2 1.3} {
	package ifneeded t $i "set x $i; package provide t $i"
    }
    set x xxx
    package require t
    set x
} {1.3}

test pkg-2.52 {Tcl_PkgRequire procedure, picking best stable version} {
    package forget t
    foreach i {1.2b1 1.2 1.3 1.3a2} {
	package ifneeded t $i "set x $i; package provide t $i"
    }
    set x xxx
    package require t
    set x
} {1.3}



test pkg-3.1 {Tcl_PackageCmd procedure} {
    list [catch {package} msg] $msg
} {1 {wrong # args: should be "package option ?arg arg ...?"}}
test pkg-3.2 {Tcl_PackageCmd procedure, "forget" option} {
    foreach i [package names] {
	package forget $i
    }
    package names
} {}
test pkg-3.3 {Tcl_PackageCmd procedure, "forget" option} {
    foreach i [package names] {
	package forget $i
    }
    package forget foo
} {}
test pkg-3.4 {Tcl_PackageCmd procedure, "forget" option} {
    foreach i [package names] {
	package forget $i
    }
    package ifneeded t 1.1 {first script}
    package ifneeded t 2.3 {second script}
    package ifneeded x 1.4 {x's script}
    set result {}
    lappend result [lsort [package names]] [package versions t]
    package forget t
    lappend result [lsort [package names]] [package versions t]
} {{t x} {1.1 2.3} x {}}
test pkg-3.5 {Tcl_PackageCmd procedure, "forget" option} {
    foreach i [package names] {
	package forget $i
    }
    package ifneeded a 1.1 {first script}
    package ifneeded b 2.3 {second script}
    package ifneeded c 1.4 {third script}
    package forget
    set result [list [lsort [package names]]]
    package forget a c
    lappend result [lsort [package names]]
} {{a b c} b}
test pkg-3.5.1 {Tcl_PackageCmd procedure, "forget" option} {
    # Test for Bug 415273
    package ifneeded a 1 "I should have been forgotten"
    package forget no-such-package a
    set x [package ifneeded a 1]
    package forget a
    set x
} {}
test pkg-3.6 {Tcl_PackageCmd procedure, "ifneeded" option} {
    list [catch {package ifneeded a} msg] $msg
} {1 {wrong # args: should be "package ifneeded package version ?script?"}}
test pkg-3.7 {Tcl_PackageCmd procedure, "ifneeded" option} {
    list [catch {package ifneeded a b c d} msg] $msg
} {1 {wrong # args: should be "package ifneeded package version ?script?"}}
test pkg-3.8 {Tcl_PackageCmd procedure, "ifneeded" option} {
    list [catch {package ifneeded t xyz} msg] $msg
} {1 {expected version number but got "xyz"}}
test pkg-3.9 {Tcl_PackageCmd procedure, "ifneeded" option} {
    foreach i [package names] {
	package forget $i
    }
    list [package ifneeded foo 1.1] [package names]
} {{} {}}
test pkg-3.10 {Tcl_PackageCmd procedure, "ifneeded" option} {
    package forget t
    package ifneeded t 1.4 "script for t 1.4"
    list [package names] [package ifneeded t 1.4] [package versions t]
} {t {script for t 1.4} 1.4}
test pkg-3.11 {Tcl_PackageCmd procedure, "ifneeded" option} {
    package forget t
    package ifneeded t 1.4 "script for t 1.4"
    list [package ifneeded t 1.5] [package names] [package versions t]
} {{} t 1.4}
test pkg-3.12 {Tcl_PackageCmd procedure, "ifneeded" option} {
    package forget t
    package ifneeded t 1.4 "script for t 1.4"
    package ifneeded t 1.4 "second script for t 1.4"
    list [package ifneeded t 1.4] [package names] [package versions t]
} {{second script for t 1.4} t 1.4}
test pkg-3.13 {Tcl_PackageCmd procedure, "ifneeded" option} {
    package forget t
    package ifneeded t 1.4 "script for t 1.4"
    package ifneeded t 1.2 "second script"
    package ifneeded t 3.1 "last script"
    list [package ifneeded t 1.2] [package versions t]
} {{second script} {1.4 1.2 3.1}}
test pkg-3.14 {Tcl_PackageCmd procedure, "names" option} {
    list [catch {package names a} msg] $msg
} {1 {wrong # args: should be "package names"}}
test pkg-3.15 {Tcl_PackageCmd procedure, "names" option} {
    foreach i [package names] {
	package forget $i
    }
    package names
} {}
test pkg-3.16 {Tcl_PackageCmd procedure, "names" option} {
    foreach i [package names] {
	package forget $i
    }
    package ifneeded x 1.2 {dummy}
    package provide x 1.3
    package provide y 2.4
    catch {package require z 47.16}
    lsort [package names]
} {x y}
test pkg-3.17 {Tcl_PackageCmd procedure, "provide" option} {
    list [catch {package provide} msg] $msg
} {1 {wrong # args: should be "package provide package ?version?"}}
test pkg-3.18 {Tcl_PackageCmd procedure, "provide" option} {
    list [catch {package provide a b c} msg] $msg
} {1 {wrong # args: should be "package provide package ?version?"}}
test pkg-3.19 {Tcl_PackageCmd procedure, "provide" option} {
    package forget t
    package provide t
} {}
test pkg-3.20 {Tcl_PackageCmd procedure, "provide" option} {
    package forget t
    package provide t 2.3
    package provide t
} {2.3}
test pkg-3.21 {Tcl_PackageCmd procedure, "provide" option} {
    package forget t
    list [catch {package provide t a.b} msg] $msg
} {1 {expected version number but got "a.b"}}
test pkg-3.22 {Tcl_PackageCmd procedure, "require" option} {
    list [catch {package require} msg] $msg
} {1 {wrong # args: should be "package require ?-exact? package ?requirement...?"}}

test pkg-3.24 {Tcl_PackageCmd procedure, "require" option} {
    list [catch {package require -exact a b c} msg] $msg
    # Exact syntax: -exact name version
    #              name ?requirement...?
} {1 {wrong # args: should be "package require ?-exact? package ?requirement...?"}}

test pkg-3.26 {Tcl_PackageCmd procedure, "require" option} {
    list [catch {package require x a.b} msg] $msg
} {1 {expected version number but got "a.b"}}
test pkg-3.27 {Tcl_PackageCmd procedure, "require" option} {
    list [catch {package require -exact x a.b} msg] $msg
} {1 {expected version number but got "a.b"}}
test pkg-3.28 {Tcl_PackageCmd procedure, "require" option} {
    list [catch {package require -exact x} msg] $msg
} {1 {wrong # args: should be "package require ?-exact? package ?requirement...?"}}
test pkg-3.29 {Tcl_PackageCmd procedure, "require" option} {
    list [catch {package require -exact} msg] $msg
} {1 {wrong # args: should be "package require ?-exact? package ?requirement...?"}}
test pkg-3.30 {Tcl_PackageCmd procedure, "require" option} {
    package forget t
    package provide t 2.3
    package require t 2.1
} {2.3}
test pkg-3.31 {Tcl_PackageCmd procedure, "require" option} {
    package forget t
    list [catch {package require t} msg] $msg
} {1 {can't find package t}}
test pkg-3.32 {Tcl_PackageCmd procedure, "require" option} {
    package forget t
    package ifneeded t 2.3 "error {synthetic error}"
    list [catch {package require t 2.3} msg] $msg
} {1 {synthetic error}}
test pkg-3.33 {Tcl_PackageCmd procedure, "unknown" option} {
    list [catch {package unknown a b} msg] $msg
} {1 {wrong # args: should be "package unknown ?command?"}}
test pkg-3.34 {Tcl_PackageCmd procedure, "unknown" option} {
    package unknown "test script"
    package unknown
} {test script}
test pkg-3.35 {Tcl_PackageCmd procedure, "unknown" option} {
    package unknown "test script"
    package unknown {}
    package unknown
} {}
test pkg-3.36 {Tcl_PackageCmd procedure, "vcompare" option} {
    list [catch {package vcompare a} msg] $msg
} {1 {wrong # args: should be "package vcompare version1 version2"}}
test pkg-3.37 {Tcl_PackageCmd procedure, "vcompare" option} {
    list [catch {package vcompare a b c} msg] $msg
} {1 {wrong # args: should be "package vcompare version1 version2"}}
test pkg-3.38 {Tcl_PackageCmd procedure, "vcompare" option} {
    list [catch {package vcompare x.y 3.4} msg] $msg
} {1 {expected version number but got "x.y"}}
test pkg-3.39 {Tcl_PackageCmd procedure, "vcompare" option} {
    list [catch {package vcompare 2.1 a.b} msg] $msg
} {1 {expected version number but got "a.b"}}
test pkg-3.40 {Tcl_PackageCmd procedure, "vcompare" option} {
    package vc 2.1 2.3
} {-1}
test pkg-3.41 {Tcl_PackageCmd procedure, "vcompare" option} {
    package vc 2.2.4 2.2.4
} {0}
test pkg-3.42 {Tcl_PackageCmd procedure, "versions" option} {
    list [catch {package versions} msg] $msg
} {1 {wrong # args: should be "package versions package"}}
test pkg-3.43 {Tcl_PackageCmd procedure, "versions" option} {
    list [catch {package versions a b} msg] $msg
} {1 {wrong # args: should be "package versions package"}}
test pkg-3.44 {Tcl_PackageCmd procedure, "versions" option} {
    package forget t
    package versions t
} {}
test pkg-3.45 {Tcl_PackageCmd procedure, "versions" option} {
    package forget t
    package provide t 2.3
    package versions t
} {}
test pkg-3.46 {Tcl_PackageCmd procedure, "versions" option} {
    package forget t
    package ifneeded t 2.3 x
    package ifneeded t 2.4 y
    package versions t
} {2.3 2.4}
test pkg-3.47 {Tcl_PackageCmd procedure, "vsatisfies" option} {
    list [catch {package vsatisfies a} msg] $msg
} {1 {wrong # args: should be "package vsatisfies version requirement requirement..."}}

test pkg-3.49 {Tcl_PackageCmd procedure, "vsatisfies" option} {
    list [catch {package vsatisfies x.y 3.4} msg] $msg
} {1 {expected version number but got "x.y"}}
test pkg-3.50 {Tcl_PackageCmd procedure, "vsatisfies" option} {
    list [catch {package vcompare 2.1 a.b} msg] $msg
} {1 {expected version number but got "a.b"}}
test pkg-3.51 {Tcl_PackageCmd procedure, "vsatisfies" option} {
    package vs 2.3 2.1
} {1}
test pkg-3.52 {Tcl_PackageCmd procedure, "vsatisfies" option} {
    package vs 2.3 1.2
} {0}
test pkg-3.53 {Tcl_PackageCmd procedure, "versions" option} {
    list [catch {package foo} msg] $msg
} {1 {bad option "foo": must be forget, ifneeded, names, prefer, present, provide, require, unknown, vcompare, versions, or vsatisfies}}

test pkg-3.54 {Tcl_PackageCmd procedure, "vsatisfies" option} {
    list [catch {package vsatisfies 2.1 2.1-3.2-4.5} msg] $msg
} {1 {expected versionMin-versionMax but got "2.1-3.2-4.5"}}

test pkg-3.55 {Tcl_PackageCmd procedure, "vsatisfies" option} {
    list [catch {package vsatisfies 2.1 3.2-x.y} msg] $msg
} {1 {expected version number but got "x.y"}}

test pkg-3.56 {Tcl_PackageCmd procedure, "vsatisfies" option} {
    list [catch {package vsatisfies 2.1 x.y-3.2} msg] $msg
} {1 {expected version number but got "x.y"}}


# No tests for FindPackage;  can't think up anything detectable
# errors.

test pkg-4.1 {TclFreePackageInfo procedure} {
    interp create foo
    foo eval {
	package ifneeded t 2.3 x
	package ifneeded t 2.4 y
	package ifneeded x 3.1 z
	package provide q 4.3
	package unknown "will this get freed?"
    }
    interp delete foo
} {}
test pkg-4.2 {TclFreePackageInfo procedure} -body {
    interp create foo
    foo eval {
	package ifneeded t 2.3 x
	package ifneeded t 2.4 y
	package ifneeded x 3.1 z
	package provide q 4.3
    }
    foo alias z kill
    proc kill {} {
	interp delete foo
    }
    foo eval package require x 3.1
} -returnCodes error -match glob -result *

test pkg-5.1 {CheckVersion procedure} {
    list [catch {package vcompare 1 2.1} msg] $msg
} {0 -1}
test pkg-5.2 {CheckVersion procedure} {
    list [catch {package vcompare .1 2.1} msg] $msg
} {1 {expected version number but got ".1"}}
test pkg-5.3 {CheckVersion procedure} {
    list [catch {package vcompare 111.2a.3 2.1} msg] $msg
} {1 {expected version number but got "111.2a.3"}}
test pkg-5.4 {CheckVersion procedure} {
    list [catch {package vcompare 1.2.3. 2.1} msg] $msg
} {1 {expected version number but got "1.2.3."}}
test pkg-5.5 {CheckVersion procedure} {
    list [catch {package vcompare 1.2..3 2.1} msg] $msg
} {1 {expected version number but got "1.2..3"}}

test pkg-6.1 {ComparePkgVersions procedure} {
    package vcompare 1.23 1.22
} {1}
test pkg-6.2 {ComparePkgVersions procedure} {
    package vcompare 1.22.1.2.3 1.22.1.2.3
} {0}
test pkg-6.3 {ComparePkgVersions procedure} {
    package vcompare 1.21 1.22
} {-1}
test pkg-6.4 {ComparePkgVersions procedure} {
    package vcompare 1.21 1.21.2
} {-1}
test pkg-6.5 {ComparePkgVersions procedure} {
    package vcompare 1.21.1 1.21
} {1}
test pkg-6.6 {ComparePkgVersions procedure} {
    package vsatisfies 1.21.1 1.21
} {1}
test pkg-6.7 {ComparePkgVersions procedure} {
    package vsatisfies 2.22.3 1.21
} {0}
test pkg-6.8 {ComparePkgVersions procedure} {
    package vsatisfies 1 1
} {1}
test pkg-6.9 {ComparePkgVersions procedure} {
    package vsatisfies 2 1
} {0}

test pkg-7.1 {Tcl_PkgPresent procedure, any version} {
    package forget t
    package provide t 2.4
    package present t
} {2.4}
test pkg-7.2 {Tcl_PkgPresent procedure, correct version} {
    package forget t
    package provide t 2.4
    package present t 2.4
} {2.4}
test pkg-7.3 {Tcl_PkgPresent procedure, satisfying version} {
    package forget t
    package provide t 2.4
    package present t 2.0
} {2.4}
test pkg-7.4 {Tcl_PkgPresent procedure, not satisfying version} {
    package forget t
    package provide t 2.4
    list [catch {package present t 2.6} msg] $msg
} {1 {version conflict for package "t": have 2.4, need 2.6}}
test pkg-7.5 {Tcl_PkgPresent procedure, not satisfying version} {
    package forget t
    package provide t 2.4
    list [catch {package present t 1.0} msg] $msg
} {1 {version conflict for package "t": have 2.4, need 1.0}}
test pkg-7.6 {Tcl_PkgPresent procedure, exact version} {
    package forget t
    package provide t 2.4
    package present -exact t 2.4
} {2.4}
test pkg-7.7 {Tcl_PkgPresent procedure, not exact version} {
    package forget t
    package provide t 2.4
    list [catch {package present -exact t 2.3} msg] $msg
} {1 {version conflict for package "t": have 2.4, need exactly 2.3}}
test pkg-7.8 {Tcl_PkgPresent procedure, unknown package} {
    package forget t
    list [catch {package present t} msg] $msg
} {1 {package t is not present}}
test pkg-7.9 {Tcl_PkgPresent procedure, unknown package} {
    package forget t
    list [catch {package present t 2.4} msg] $msg
} {1 {package t 2.4 is not present}}
test pkg-7.10 {Tcl_PkgPresent procedure, unknown package} {
    package forget t
    list [catch {package present -exact t 2.4} msg] $msg
} {1 {package t 2.4 is not present}}
test pkg-7.11 {Tcl_PackageCmd procedure, "present" option} {
    list [catch {package present} msg] $msg
} {1 {wrong # args: should be "package present ?-exact? package ?requirement...?"}}
test pkg-7.12 {Tcl_PackageCmd procedure, "present" option} {
    list [catch {package present a b c} msg] $msg
} {1 {expected version number but got "b"}}
test pkg-7.13 {Tcl_PackageCmd procedure, "present" option} {
    list [catch {package present -exact a b c} msg] $msg
} {1 {wrong # args: should be "package present ?-exact? package ?requirement...?"}}
test pkg-7.14 {Tcl_PackageCmd procedure, "present" option} {
    list [catch {package present -bs a b} msg] $msg
} {1 {expected version number but got "a"}}
test pkg-7.15 {Tcl_PackageCmd procedure, "present" option} {
    list [catch {package present x a.b} msg] $msg
} {1 {expected version number but got "a.b"}}
test pkg-7.16 {Tcl_PackageCmd procedure, "present" option} {
    list [catch {package present -exact x a.b} msg] $msg
} {1 {expected version number but got "a.b"}}
test pkg-7.17 {Tcl_PackageCmd procedure, "present" option} {
    list [catch {package present -exact x} msg] $msg
} {1 {wrong # args: should be "package present ?-exact? package ?requirement...?"}}
test pkg-7.18 {Tcl_PackageCmd procedure, "present" option} {
    list [catch {package present -exact} msg] $msg
} {1 {wrong # args: should be "package present ?-exact? package ?requirement...?"}}




set n 0
foreach {r p vs vc} {
    8.5a0    8.5a5    1          -1
    8.5a0    8.5b1    1          -1
    8.5a0    8.5.1    1          -1
    8.5a0    8.6a0    1          -1
    8.5a0    8.6b0    1          -1
    8.5a0    8.6.0    1          -1
    8.5a6    8.5a5    0          1
    8.5a6    8.5b1    1          -1
    8.5a6    8.5.1    1          -1
    8.5a6    8.6a0    1          -1
    8.5a6    8.6b0    1          -1
    8.5a6    8.6.0    1          -1
    8.5b0    8.5a5    0          1
    8.5b0    8.5b1    1          -1
    8.5b0    8.5.1    1          -1
    8.5b0    8.6a0    1          -1
    8.5b0    8.6b0    1          -1
    8.5b0    8.6.0    1          -1
    8.5b2    8.5a5    0          1
    8.5b2    8.5b1    0          1
    8.5b2    8.5.1    1          -1
    8.5b2    8.6a0    1          -1
    8.5b2    8.6b0    1          -1
    8.5b2    8.6.0    1          -1
    8.5      8.5a5    1          1
    8.5      8.5b1    1          1
    8.5      8.5.1    1          -1
    8.5      8.6a0    1          -1
    8.5      8.6b0    1          -1
    8.5      8.6.0    1          -1
    8.5.0    8.5a5    0          1
    8.5.0    8.5b1    0          1
    8.5.0    8.5.1    1          -1
    8.5.0    8.6a0    1          -1
    8.5.0    8.6b0    1          -1
    8.5.0    8.6.0    1          -1
    10       8        0          1
    8        10       0          -1
    0.0.1.2  0.1.2    1          -1
} {
    test package-vsatisfies-1.$n {package vsatisfies} {
	package vsatisfies $p $r
    } $vs

    test package-vcompare-1.$n {package vcompare} {
	package vcompare $r $p
    } $vc

    incr n
}

test package-vcompare-2.0 {package vcompare at 32bit boundary} {
    package vcompare [expr {1<<31}] [expr {(1<<31)-1}]
} 1

# Note: It is correct that the result of the very first test,
# i.e. "5.0 5.0a0" is 1, i.e. that version 5.0a0 satisfies a 5.0
# requirement.

# The requirement "5.0" internally translates first to "5.0-6", and
# then to its final form of "5.0a0-6a0". These translations are
# explicitly specified by the TIP (Search for "padded/extended
# internally with 'a0'"). This was done intentionally for exactly the
# tested case, that an alpha package can satisfy a requirement for the
# regular package. An example would be a package FOO requiring Tcl 8.X
# for its operation. It can be used with Tcl 8.Xa0. Without our
# translation that would not be possible.

set n 0
foreach {required provided satisfied} {
    5.0 5.0a0 1
    5.0a0 5.0 1

    8.5a0-   8.5a5    1
    8.5a0-   8.5b1    1
    8.5a0-   8.5.1    1
    8.5a0-   8.6a0    1
    8.5a0-   8.6b0    1
    8.5a0-   8.6.0    1
    8.5a6-   8.5a5    0
    8.5a6-   8.5b1    1
    8.5a6-   8.5.1    1
    8.5a6-   8.6a0    1
    8.5a6-   8.6b0    1
    8.5a6-   8.6.0    1
    8.5b0-   8.5a5    0
    8.5b0-   8.5b1    1
    8.5b0-   8.5.1    1
    8.5b0-   8.6a0    1
    8.5b0-   8.6b0    1
    8.5b0-   8.6.0    1
    8.5b2-   8.5a5    0
    8.5b2-   8.5b1    0
    8.5b2-   8.5.1    1
    8.5b2-   8.6a0    1
    8.5b2-   8.6b0    1
    8.5b2-   8.6.0    1
    8.5-     8.5a5    1
    8.5-     8.5b1    1
    8.5-     8.5.1    1
    8.5-     8.6a0    1
    8.5-     8.6b0    1
    8.5-     8.6.0    1
    8.5.0-   8.5a5    0
    8.5.0-   8.5b1    0
    8.5.0-   8.5.1    1
    8.5.0-   8.6a0    1
    8.5.0-   8.6b0    1
    8.5.0-   8.6.0    1
    8.5a0-7  8.5a5    0
    8.5a0-7  8.5b1    0
    8.5a0-7  8.5.1    0
    8.5a0-7  8.6a0    0
    8.5a0-7  8.6b0    0
    8.5a0-7  8.6.0    0
    8.5a6-7  8.5a5    0
    8.5a6-7  8.5b1    0
    8.5a6-7  8.5.1    0
    8.5a6-7  8.6a0    0
    8.5a6-7  8.6b0    0
    8.5a6-7  8.6.0    0
    8.5b0-7  8.5a5    0
    8.5b0-7  8.5b1    0
    8.5b0-7  8.5.1    0
    8.5b0-7  8.6a0    0
    8.5b0-7  8.6b0    0
    8.5b0-7  8.6.0    0
    8.5b2-7  8.5a5    0
    8.5b2-7  8.5b1    0
    8.5b2-7  8.5.1    0
    8.5b2-7  8.6a0    0
    8.5b2-7  8.6b0    0
    8.5b2-7  8.6.0    0
    8.5-7    8.5a5    0
    8.5-7    8.5b1    0
    8.5-7    8.5.1    0
    8.5-7    8.6a0    0
    8.5-7    8.6b0    0
    8.5-7    8.6.0    0
    8.5.0-7  8.5a5    0
    8.5.0-7  8.5b1    0
    8.5.0-7  8.5.1    0
    8.5.0-7  8.6a0    0
    8.5.0-7  8.6b0    0
    8.5.0-7  8.6.0    0
    8.5a0-8.6.1 8.5a5    1
    8.5a0-8.6.1 8.5b1    1
    8.5a0-8.6.1 8.5.1    1
    8.5a0-8.6.1 8.6a0    1
    8.5a0-8.6.1 8.6b0    1
    8.5a0-8.6.1 8.6.0    1
    8.5a6-8.6.1 8.5a5    0
    8.5a6-8.6.1 8.5b1    1
    8.5a6-8.6.1 8.5.1    1
    8.5a6-8.6.1 8.6a0    1
    8.5a6-8.6.1 8.6b0    1
    8.5a6-8.6.1 8.6.0    1
    8.5b0-8.6.1 8.5a5    0
    8.5b0-8.6.1 8.5b1    1
    8.5b0-8.6.1 8.5.1    1
    8.5b0-8.6.1 8.6a0    1
    8.5b0-8.6.1 8.6b0    1
    8.5b0-8.6.1 8.6.0    1
    8.5b2-8.6.1 8.5a5    0
    8.5b2-8.6.1 8.5b1    0
    8.5b2-8.6.1 8.5.1    1
    8.5b2-8.6.1 8.6a0    1
    8.5b2-8.6.1 8.6b0    1
    8.5b2-8.6.1 8.6.0    1
    8.5-8.6.1 8.5a5    1
    8.5-8.6.1 8.5b1    1
    8.5-8.6.1 8.5.1    1
    8.5-8.6.1 8.6a0    1
    8.5-8.6.1 8.6b0    1
    8.5-8.6.1 8.6.0    1
    8.5.0-8.6.1 8.5a5    0
    8.5.0-8.6.1 8.5b1    0
    8.5.0-8.6.1 8.5.1    1
    8.5.0-8.6.1 8.6a0    1
    8.5.0-8.6.1 8.6b0    1
    8.5.0-8.6.1 8.6.0    1
    8.5a0-8.5a0 8.5a0    1
    8.5a0-8.5a0 8.5b1    0
    8.5a0-8.5a0 8.4      0
    8.5b0-8.5b0 8.5a5    0
    8.5b0-8.5b0 8.5b0    1
    8.5b0-8.5b0 8.5.1    0
    8.5-8.5  8.5a5    0
    8.5-8.5  8.5b1    0
    8.5-8.5  8.5      1
    8.5-8.5  8.5.1    0
    8.5.0-8.5.0 8.5a5    0
    8.5.0-8.5.0 8.5b1    0
    8.5.0-8.5.0 8.5.0    1
    8.5.0-8.5.0 8.5.1    0
    8.5.0-8.5.0 8.6a0    0
    8.5.0-8.5.0 8.6b0    0
    8.5.0-8.5.0 8.6.0    0
    8.2      9        0
    8.2-     9        1
    8.2-8.5  9        0
    8.2-9.1  9        1

    8.5-8.5     8.5b1 0
    8.5a0-8.5   8.5b1 0
    8.5a0-8.5.1 8.5b1 1

    8.5-8.5     8.5 1
    8.5.0-8.5.0 8.5 1
    8.5a0-8.5.0 8.5 0

} {
    test package-vsatisfies-2.$n "package vsatisfies $provided $required" {
	package vsatisfies $provided $required
    } $satisfied
    incr n
}

test package-vsatisfies-3.0 "package vsatisfies multiple" {
    #                      yes no
    package vsatisfies 8.4 8.4 7.3
} 1

test package-vsatisfies-3.1 "package vsatisfies multiple" {
    #                      no  yes
    package vsatisfies 8.4 7.3 8.4
} 1

test package-vsatisfies-3.2 "package vsatisfies multiple" {
    #                        yes  yes
    package vsatisfies 8.4.2 8.4  8.4.1
} 1

test package-vsatisfies-3.3 "package vsatisfies multiple" {
    #                      no  no
    package vsatisfies 8.4 7.3 6.1
} 0


proc prefer {args} {
    set ip [interp create]
    lappend res [$ip eval {package prefer}]
    foreach mode $args {
	lappend res [$ip eval [list package prefer $mode]]
    }
    interp delete $ip
    return $res
}

test package-prefer-1.0 {default} {
    prefer
} stable

test package-prefer-1.1 {default} {
    set   ::env(TCL_PKG_PREFER_LATEST) stable ; # value not relevant!
    set res [prefer]
    unset ::env(TCL_PKG_PREFER_LATEST)
    set res
} latest

test package-prefer-2.0 {wrong\#args} {
    catch {package prefer foo bar} msg
    set msg
} {wrong # args: should be "package prefer ?latest|stable?"}

test package-prefer-2.1 {bogus argument} {
    catch {package prefer foo} msg
    set msg
} {bad preference "foo": must be latest or stable}

test package-prefer-3.0 {set, keep} {
    package prefer stable
} stable

test package-prefer-3.1 {set stable, keep} {
    prefer stable
} {stable stable}

test package-prefer-3.2 {set latest, change} {
    prefer latest
} {stable latest}

test package-prefer-3.3 {set latest, keep} {
    prefer  latest latest
} {stable latest latest}

test package-prefer-3.4 {set stable, rejected} {
    prefer latest stable
} {stable latest latest}

rename prefer {}


set auto_path $oldPath
package unknown $oldPkgUnknown
concat

cleanupTests
}

# cleanup
interp delete $i
::tcltest::cleanupTests
return
s */ char *name; /*name generator printf format */ unsigned flags; /*flags for opening additional members */ } H5FD_family_t; </PRE> <P> <STRONG>Example:</STRONG> The sec2 driver needs to keep track of the underlying Unix file descriptor and also the end of format address space and current Unix file size. It also keeps track of the current file position and last operation (read, write, or unknown) in order to optimize calls to <CODE>lseek</CODE>. The <CODE>device</CODE> and <CODE>inode</CODE> fields are defined on Unix in order to uniquely identify the file and will be discussed below. </P> <PRE> typedef struct H5FD_sec2_t { H5FD_t pub; /*public stuff, must be first */ int fd; /*the unix file */ haddr_t eoa; /*end of allocated region */ haddr_t eof; /*end of file; current file size*/ haddr_t pos; /*current file I/O position */ int op; /*last operation */ dev_t device; /*file device number */ ino_t inode; /*file i-node number */ } H5FD_sec2_t; </PRE> <H3><A NAME="SEC10" HREF="#TOC10">Opening Files</A></H3> <P> All drivers must define a function for opening/creating a file. This function should have a prototype which is: </P> <P> <DL> <DT><U>Function:</U> static H5FD_t * <B>open</B> <I>(const char *<VAR>name</VAR>, unsigned <VAR>flags</VAR>, hid_t <VAR>fapl</VAR>, haddr_t <VAR>maxaddr</VAR>)</I> <DD><A NAME="IDX1"></A> </P> <P> The file name <VAR>name</VAR> and file access property list <VAR>fapl</VAR> are the same as were specified in the <CODE>H5Fcreate</CODE> or <CODE>H5Fopen</CODE> call. The <VAR>flags</VAR> are the same as in those calls also except the flag <CODE>H5F_ACC_CREATE</CODE> is also present if the call was to <CODE>H5Fcreate</CODE> and they are documented in the <TT>`H5Fpublic.h'</TT> file. The <VAR>maxaddr</VAR> argument is the maximum format address that the driver should be prepared to handle (the minimum address is always zero). </DL> </P> <P> <STRONG>Example:</STRONG> The sec2 driver opens a Unix file with the requested name and saves information which uniquely identifies the file (the Unix device number and inode). </P> <PRE> static H5FD_t * H5FD_sec2_open(const char *name, unsigned flags, hid_t fapl_id/*unused*/, haddr_t maxaddr) { unsigned o_flags; int fd; struct stat sb; H5FD_sec2_t *file=NULL; /* Check arguments */ if (!name || !*name) return NULL; if (0==maxaddr || HADDR_UNDEF==maxaddr) return NULL; if (ADDR_OVERFLOW(maxaddr)) return NULL; /* Build the open flags */ o_flags = (H5F_ACC_RDWR &#38; flags) ? O_RDWR : O_RDONLY; if (H5F_ACC_TRUNC &#38; flags) o_flags |= O_TRUNC; if (H5F_ACC_CREAT &#38; flags) o_flags |= O_CREAT; if (H5F_ACC_EXCL &#38; flags) o_flags |= O_EXCL; /* Open the file */ if ((fd=open(name, o_flags, 0666))&#60;0) return NULL; if (fstat(fd, &#38;sb)&#60;0) { close(fd); return NULL; } /* Create the new file struct */ file = calloc(1, sizeof(H5FD_sec2_t)); file-&#62;fd = fd; file-&#62;eof = sb.st_size; file-&#62;pos = HADDR_UNDEF; file-&#62;op = OP_UNKNOWN; file-&#62;device = sb.st_dev; file-&#62;inode = sb.st_ino; return (H5FD_t*)file; } </PRE> <H3><A NAME="SEC11" HREF="#TOC11">Closing Files</A></H3> <P> Closing a file simply means that all cached data should be flushed to the next lower layer, the file should be closed at the next lower layer, and all file-related data structures should be freed. All information needed by the close function is already present in the file handle. </P> <P> <DL> <DT><U>Function:</U> static herr_t <B>close</B> <I>(H5FD_t *<VAR>file</VAR>)</I> <DD><A NAME="IDX2"></A> </P> <P> The <VAR>file</VAR> argument is the handle which was returned by the <CODE>open</CODE> function, and the <CODE>close</CODE> should free only memory associated with the driver-specific part of the handle (the public parts will have already been released by HDF5's virtual file layer). </DL> </P> <P> <STRONG>Example:</STRONG> The sec2 driver just closes the underlying Unix file, making sure that the actual file size is the same as that known to the library by writing a zero to the last file position it hasn't been written by some previous operation (which happens in the same code which flushes the file contents and is shown below). </P> <PRE> static herr_t H5FD_sec2_close(H5FD_t *_file) { H5FD_sec2_t *file = (H5FD_sec2_t*)_file; if (H5FD_sec2_flush(_file)&#60;0) return -1; if (close(file-&#62;fd)&#60;0) return -1; free(file); return 0; } </PRE> <H3><A NAME="SEC12" HREF="#TOC12">File Keys</A></H3> <P> Occasionally an application will attempt to open a single file more than one time in order to obtain multiple handles to the file. HDF5 allows the files to share information<A NAME="DOCF6" HREF="#FOOT6">(6)</A> but in order to accomplish this HDF5 must be able to tell when two names refer to the same file. It does this by associating a driver-defined key with each file opened by a driver and comparing the key for an open request with the keys for all other files currently open by the same driver. </P> <P> <DL> <DT><U>Function:</U> const int <B>cmp</B> <I>(const H5FD_t *<VAR>f1</VAR>, const H5FD_t *<VAR>f2</VAR>)</I> <DD><A NAME="IDX3"></A> </P> <P> The driver may provide a function which compares two files <VAR>f1</VAR> and <VAR>f2</VAR> belonging to the same driver and returns a negative, positive, or zero value <I>a la</I> the <CODE>strcmp</CODE> function.<A NAME="DOCF7" HREF="#FOOT7">(7)</A> If this function is not provided then HDF5 assumes that all calls to the <CODE>open</CODE> callback return unique files regardless of the arguments and it is up to the application to avoid doing this if that assumption is incorrect. </DL> </P> <P> Each time a file is opened the library calls the <CODE>cmp</CODE> function to compare that file with all other files currently open by the same driver and if one of them matches (at most one can match) then the file which was just opened is closed and the previously opened file is used instead. </P> <P> Opening a file twice with incompatible flags will result in failure. For instance, opening a file with the truncate flag is a two step process which first opens the file without truncation so keys can be compared, and if no matching file is found already open then the file is closed and immediately reopened with the truncation flag set (if a matching file is already open then the truncating open will fail). </P> <P> <STRONG>Example:</STRONG> The sec2 driver uses the Unix device and i-node as the key. They were initialized when the file was opened. </P> <PRE> static int H5FD_sec2_cmp(const H5FD_t *_f1, const H5FD_t *_f2) { const H5FD_sec2_t *f1 = (const H5FD_sec2_t*)_f1; const H5FD_sec2_t *f2 = (const H5FD_sec2_t*)_f2; if (f1-&#62;device &#60; f2-&#62;device) return -1; if (f1-&#62;device &#62; f2-&#62;device) return 1; if (f1-&#62;inode &#60; f2-&#62;inode) return -1; if (f1-&#62;inode &#62; f2-&#62;inode) return 1; return 0; } </PRE> <H3><A NAME="SEC13" HREF="#TOC13">Saving Modes Across Opens</A></H3> <P> Some drivers may also need to store certain information in the file superblock in order to be able to reliably open the file at a later date. This is done by three functions: one to determine how much space will be necessary to store the information in the superblock, one to encode the information, and one to decode the information. These functions are optional, but if any one is defined then the other two must also be defined. </P> <P> <DL> <DT><U>Function:</U> static hsize_t <B>sb_size</B> <I>(H5FD_t *<VAR>file</VAR>)</I> <DD><A NAME="IDX4"></A> <DT><U>Function:</U> static herr_t <B>sb_encode</B> <I>(H5FD_t *<VAR>file</VAR>, char *<VAR>name</VAR>, unsigned char *<VAR>buf</VAR>)</I> <DD><A NAME="IDX5"></A> <DT><U>Function:</U> static herr_t <B>sb_decode</B> <I>(H5FD_t *<VAR>file</VAR>, const char *<VAR>name</VAR>, const unsigned char *<VAR>buf</VAR>)</I> <DD><A NAME="IDX6"></A> </P> <P> The <CODE>sb_size</CODE> function returns the number of bytes necessary to encode information needed later if the file is reopened. The <CODE>sb_encode</CODE> function encodes information from the file into buffer <VAR>buf</VAR> allocated by the caller. It also writes an 8-character (plus null termination) into the <CODE>name</CODE> argument, which should be a unique identification for the driver. The <CODE>sb_decode</CODE> function looks at the <VAR>name</VAR> </P> <P> decodes data from the buffer <VAR>buf</VAR> and updates the <VAR>file</VAR> argument with the new information, advancing <VAR>*p</VAR> in the process. </DL> </P> <P> The part of this which is somewhat tricky is that the file must be readable before the superblock information is decoded. File access modes fall outside the scope of the HDF5 file format, but they are placed inside the boot block for convenience.<A NAME="DOCF8" HREF="#FOOT8">(8)</A> </P> <P> <STRONG>Example:</STRONG> <EM>To be written later.</EM> </P> <H2><A NAME="SEC14" HREF="#TOC14">Address Space Functions</A></H2> <P> HDF5 does not assume that a file is a linear address space of bytes. Instead, the library will call functions to allocate and free portions of the HDF5 format address space, which in turn map onto functions in the file driver to allocate and free portions of file address space. The library tells the file driver how much format address space it wants to allocate and the driver decides what format address to use and how that format address is mapped onto the file address space. Usually the format address is chosen so that the file address can be calculated in constant time for data I/O operations (which are always specified by format addresses). </P> <H3><A NAME="SEC15" HREF="#TOC15">Userblock and Superblock</A></H3> <P> The HDF5 format allows an optional userblock to appear before the actual HDF5 data in such a way that if the userblock is <STRONG>sucked out</STRONG> of the file and everything remaining is shifted downward in the file address space, then the file is still a valid HDF5 file. The userblock size can be zero or any multiple of two greater than or equal to 512 and the file superblock begins immediately after the userblock. </P> <P> HDF5 allocates space for the userblock and superblock by calling an allocation function defined below, which must return a chunk of memory at format address zero on the first call. </P> <H3><A NAME="SEC16" HREF="#TOC16">Allocation of Format Regions</A></H3> <P> The library makes many types of allocation requests: </P> <DL COMPACT> <DT><CODE>H5FD_MEM_SUPER</CODE> <DD> An allocation request for the userblock and/or superblock. <DT><CODE>H5FD_MEM_BTREE</CODE> <DD> An allocation request for a node of a B-tree. <DT><CODE>H5FD_MEM_DRAW</CODE> <DD> An allocation request for the raw data of a dataset. <DT><CODE>H5FD_MEM_META</CODE> <DD> An allocation request for the raw data of a dataset which the user has indicated will be relatively small. <DT><CODE>H5FD_MEM_GROUP</CODE> <DD> An allocation request for a group leaf node (internal nodes of the group tree are allocated as H5MF_BTREE). <DT><CODE>H5FD_MEM_GHEAP</CODE> <DD> An allocation request for a global heap collection. Global heaps are used to store certain types of references such as dataset region references. The set of all global heap collections can become quite large. <DT><CODE>H5FD_MEM_LHEAP</CODE> <DD> An allocation request for a local heap. Local heaps are used to store the names which are members of a group. The combined size of all local heaps is a function of the number of object names in the file. <DT><CODE>H5FD_MEM_OHDR</CODE> <DD> An allocation request for (part of) an object header. Object headers are relatively small and include meta information about objects (like the data space and type of a dataset) and attributes. </DL> <P> When a chunk of memory is freed the library adds it to a free list and allocation requests are satisfied from the free list before requesting memory from the file driver. Each type of allocation request enumerated above has its own free list, but the file driver can specify that certain object types can share a free list. It does so by providing an array which maps a request type to a free list. If any value of the map is <CODE>H5MF_DEFAULT</CODE> (zero) then the object's own free list is used. The special value <CODE>H5MF_NOLIST</CODE> indicates that the library should not attempt to maintain a free list for that particular object type, instead calling the file driver each time an object of that type is freed. </P> <P> Mappings predefined in the <TT>`H5FDpublic.h'</TT> file are: <DL COMPACT> <DT><CODE>H5FD_FLMAP_SINGLE</CODE> <DD> All memory usage types are mapped to a single free list. <DT><CODE>H5FD_FLMAP_DICHOTOMY</CODE> <DD> Memory usage is segregated into meta data and raw data for the purposes of memory management. <DT><CODE>H5FD_FLMAP_DEFAULT</CODE> <DD> Each memory usage type has its own free list. </DL> <P> <STRONG>Example:</STRONG> To make a map that manages object headers on one free list and everything else on another free list one might initialize the map with the following code: (the use of <CODE>H5FD_MEM_SUPER</CODE> is arbitrary) </P> <PRE> H5FD_mem_t mt, map[H5FD_MEM_NTYPES]; for (mt=0; mt&#60;H5FD_MEM_NTYPES; mt++) { map[mt] = (H5FD_MEM_OHDR==mt) ? mt : H5FD_MEM_SUPER; } </PRE> <P> If an allocation request cannot be satisfied from the free list then one of two things happen. If the driver defines an allocation callback then it is used to allocate space; otherwise new memory is allocated from the end of the format address space by incrementing the end-of-address marker. </P> <P> <DL> <DT><U>Function:</U> static haddr_t <B>alloc</B> <I>(H5FD_t *<VAR>file</VAR>, H5MF_type_t <VAR>type</VAR>, hsize_t <VAR>size</VAR>)</I> <DD><A NAME="IDX7"></A> </P> <P> The <VAR>file</VAR> argument is the file from which space is to be allocated, <VAR>type</VAR> is the type of memory being requested (from the list above) without being mapped according to the freelist map and <VAR>size</VAR> is the number of bytes being requested. The library is allowed to allocate large chunks of storage and manage them in a layer above the file driver (although the current library doesn't do that). The allocation function should return a format address for the first byte allocated. The allocated region extends from that address for <VAR>size</VAR> bytes. If the request cannot be honored then the undefined address value is returned (<CODE>HADDR_UNDEF</CODE>). The first call to this function for a file which has never had memory allocated <EM>must</EM> return a format address of zero or <CODE>HADDR_UNDEF</CODE> since this is how the library allocates space for the userblock and/or superblock. </DL> </P> <P> <STRONG>Example:</STRONG> <EM>To be written later.</EM> </P> <H3><A NAME="SEC17" HREF="#TOC17">Freeing Format Regions</A></H3> <P> When the library is finished using a certain region of the format address space it will return the space to the free list according to the type of memory being freed and the free list map described above. If the free list has been disabled for a particular memory usage type (according to the free list map) and the driver defines a <CODE>free</CODE> callback then it will be invoked. The <CODE>free</CODE> callback is also invoked for all entries on the free list when the file is closed. </P> <P> <DL> <DT><U>Function:</U> static herr_t <B>free</B> <I>(H5FD_t *<VAR>file</VAR>, H5MF_type_t <VAR>type</VAR>, haddr_t <VAR>addr</VAR>, hsize_t <VAR>size</VAR>)</I> <DD><A NAME="IDX8"></A> </P> <P> The <VAR>file</VAR> argument is the file for which space is being freed; <VAR>type</VAR> is the type of object being freed (from the list above) without being mapped according to the freelist map; <VAR>addr</VAR> is the first format address to free; and <VAR>size</VAR> is the size in bytes of the region being freed. The region being freed may refer to just part of the region originally allocated and/or may cross allocation boundaries provided all regions being freed have the same usage type. However, the library will never attempt to free regions which have already been freed or which have never been allocated. </DL> </P> <P> A driver may choose to not define the <CODE>free</CODE> function, in which case format addresses will be leaked. This isn't normally a huge problem since the library contains a simple free list of its own and freeing parts of the format address space is not a common occurrence. </P> <P> <STRONG>Example:</STRONG> <EM>To be written later.</EM> </P> <H3><A NAME="SEC18" HREF="#TOC18">Querying Address Range</A></H3> <P> Each file driver must have some mechanism for setting and querying the end of address, or <STRONG>EOA</STRONG>, marker. The EOA marker is the first format address after the last format address ever allocated. If the last part of the allocated address range is freed then the driver may optionally decrease the eoa marker. </P> <P> <DL> <DT><U>Function:</U> static haddr_t <B>get_eoa</B> <I>(H5FD_t *<VAR>file</VAR>)</I> <DD><A NAME="IDX9"></A> </P> <P> This function returns the current value of the EOA marker for the specified file. </DL> </P> <P> <STRONG>Example:</STRONG> The sec2 driver just returns the current eoa marker value which is cached in the file structure: </P> <PRE> static haddr_t H5FD_sec2_get_eoa(H5FD_t *_file) { H5FD_sec2_t *file = (H5FD_sec2_t*)_file; return file-&#62;eoa; } </PRE> <P> The eoa marker is initially zero when a file is opened and the library may set it to some other value shortly after the file is opened (after the superblock is read and the saved eoa marker is determined) or when allocating additional memory in the absence of an <CODE>alloc</CODE> callback (described above). </P> <P> <STRONG>Example:</STRONG> The sec2 driver simply caches the eoa marker in the file structure and does not extend the underlying Unix file. When the file is flushed or closed then the Unix file size is extended to match the eoa marker. </P> <PRE> static herr_t H5FD_sec2_set_eoa(H5FD_t *_file, haddr_t addr) { H5FD_sec2_t *file = (H5FD_sec2_t*)_file; file-&#62;eoa = addr; return 0; } </PRE> <H2><A NAME="SEC19" HREF="#TOC19">Data Functions</A></H2> <P> These functions operate on data, transferring a region of the format address space between memory and files. </P> <H3><A NAME="SEC20" HREF="#TOC20">Contiguous I/O Functions</A></H3> <P> A driver must specify two functions to transfer data from the library to the file and vice versa. </P> <P> <DL> <DT><U>Function:</U> static herr_t <B>read</B> <I>(H5FD_t *<VAR>file</VAR>, H5FD_mem_t <VAR>type</VAR>, hid_t <VAR>dxpl</VAR>, haddr_t <VAR>addr</VAR>, hsize_t <VAR>size</VAR>, void *<VAR>buf</VAR>)</I> <DD><A NAME="IDX10"></A> <DT><U>Function:</U> static herr_t <B>write</B> <I>(H5FD_t *<VAR>file</VAR>, H5FD_mem_t <VAR>type</VAR>, hid_t <VAR>dxpl</VAR>, haddr_t <VAR>addr</VAR>, hsize_t <VAR>size</VAR>, const void *<VAR>buf</VAR>)</I> <DD><A NAME="IDX11"></A> </P> <P> The <CODE>read</CODE> function reads data from file <VAR>file</VAR> beginning at address <VAR>addr</VAR> and continuing for <VAR>size</VAR> bytes into the buffer <VAR>buf</VAR> supplied by the caller. The <CODE>write</CODE> function transfers data in the opposite direction. Both functions take a data transfer property list <VAR>dxpl</VAR> which indicates the fine points of how the data is to be transferred and which comes directly from the <CODE>H5Dread</CODE> or <CODE>H5Dwrite</CODE> function. Both functions receive <VAR>type</VAR> of data being written, which may allow a driver to tune it's behavior for different kinds of data. </DL> </P> <P> Both functions should return a negative value if they fail to transfer the requested data, or non-negative if they succeed. The library will never attempt to read from unallocated regions of the format address space. </P> <P> <STRONG>Example:</STRONG> The sec2 driver just makes system calls. It tries not to call <CODE>lseek</CODE> if the current operation is the same as the previous operation and the file position is correct. It also fills the output buffer with zeros when reading between the current EOF and EOA markers and restarts system calls which were interrupted. </P> <PRE> static herr_t H5FD_sec2_read(H5FD_t *_file, H5FD_mem_t type/*unused*/, hid_t dxpl_id/*unused*/, haddr_t addr, hsize_t size, void *buf/*out*/) { H5FD_sec2_t *file = (H5FD_sec2_t*)_file; ssize_t nbytes; assert(file &#38;&#38; file-&#62;pub.cls); assert(buf); /* Check for overflow conditions */ if (REGION_OVERFLOW(addr, size)) return -1; if (addr+size&#62;file-&#62;eoa) return -1; /* Seek to the correct location */ if ((addr!=file-&#62;pos || OP_READ!=file-&#62;op) &#38;&#38; file_seek(file-&#62;fd, (file_offset_t)addr, SEEK_SET)&#60;0) { file-&#62;pos = HADDR_UNDEF; file-&#62;op = OP_UNKNOWN; return -1; } /* * Read data, being careful of interrupted system calls, partial results, * and the end of the file. */ while (size&#62;0) { do nbytes = read(file-&#62;fd, buf, size); while (-1==nbytes &#38;&#38; EINTR==errno); if (-1==nbytes) { /* error */ file-&#62;pos = HADDR_UNDEF; file-&#62;op = OP_UNKNOWN; return -1; } if (0==nbytes) { /* end of file but not end of format address space */ memset(buf, 0, size); size = 0; } assert(nbytes&#62;=0); assert((hsize_t)nbytes&#60;=size); size -= (hsize_t)nbytes; addr += (haddr_t)nbytes; buf = (char*)buf + nbytes; } /* Update current position */ file-&#62;pos = addr; file-&#62;op = OP_READ; return 0; } </PRE> <P> <STRONG>Example:</STRONG> The sec2 <CODE>write</CODE> callback is similar except it updates the file EOF marker when extending the file. </P> <H3><A NAME="SEC21" HREF="#TOC21">Flushing Cached Data</A></H3> <P> Some drivers may desire to cache data in memory in order to make larger I/O requests to the underlying file and thus improving bandwidth. Such drivers should register a cache flushing function so that the library can insure that data has been flushed out of the drivers in response to the application calling <CODE>H5Fflush</CODE>. </P> <P> <DL> <DT><U>Function:</U> static herr_t <B>flush</B> <I>(H5FD_t *<VAR>file</VAR>)</I> <DD><A NAME="IDX12"></A> </P> <P> Flush all data for file <VAR>file</VAR> to storage. </DL> </P> <P> <STRONG>Example:</STRONG> The sec2 driver doesn't cache any data but it also doesn't extend the Unix file as aggressively as it should. Therefore, when finalizing a file it should write a zero to the last byte of the allocated region so that when reopening the file later the EOF marker will be at least as large as the EOA marker saved in the superblock (otherwise HDF5 will refuse to open the file, claiming that the data appears to be truncated). </P> <PRE> static herr_t H5FD_sec2_flush(H5FD_t *_file) { H5FD_sec2_t *file = (H5FD_sec2_t*)_file; if (file-&#62;eoa&#62;file-&#62;eof) { if (-1==file_seek(file-&#62;fd, file-&#62;eoa-1, SEEK_SET)) return -1; if (write(file-&#62;fd, "", 1)!=1) return -1; file-&#62;eof = file-&#62;eoa; file-&#62;pos = file-&#62;eoa; file-&#62;op = OP_WRITE; } return 0; } </PRE> <H2><A NAME="SEC22" HREF="#TOC22">Optimization Functions</A></H2> <P> The library is capable of performing several generic optimizations on I/O, but these types of optimizations may not be appropriate for a given VFL driver. </P> <P> Each driver may provide a query function to allow the library to query whether to enable these optimizations. If a driver lacks a query function, the library will disable all types of optimizations which can be queried. </P> <P> <DL> <DT><U>Function:</U> static herr_t <B>query</B> <I>(const H5FD_t *<VAR>file</VAR>, unsigned long *<VAR>flags</VAR>)</I> <DD><A NAME="IDX17"></A> </P> <P> This function is called by the library to query which optimizations to enable for I/O to this driver. These are the flags which are currently defined: <UL> <DL> <DT>H5FD_FEAT_AGGREGATE_METADATA (0x00000001) <DD>Defining the H5FD_FEAT_AGGREGATE_METADATA for a VFL driver means that the library will attempt to allocate a larger block for metadata and then sub-allocate each metadata request from that larger block. <DT>H5FD_FEAT_ACCUMULATE_METADATA (0x00000002) <DD>Defining the H5FD_FEAT_ACCUMULATE_METADATA for a VFL driver means that the library will attempt to cache metadata as it is written to the file and build up a larger block of metadata to eventually pass to the VFL 'write' routine. <DT>H5FD_FEAT_DATA_SIEVE (0x00000004) <DD>Defining the H5FD_FEAT_DATA_SIEVE for a VFL driver means that the library will attempt to cache raw data as it is read from/written to a file in a "data sieve" buffer. See Rajeev Thakur's papers: <UL> <DL> <DT>http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz <DT>http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz </DL> </UL> </DL> </UL> </P> </DL> </P> <H2><A NAME="SEC23" HREF="#TOC23">Registration of a Driver</A></H2> <P> Before a driver can be used the HDF5 library needs to be told of its existence. This is done by registering the driver, which results in a driver identification number. Instead of passing many arguments to the registration function, the driver information is entered into a structure and the address of the structure is passed to the registration function where it is copied. This allows the HDF5 API to be extended while providing backward compatibility at the source level. </P> <P> <DL> <DT><U>Function:</U> hid_t <B>H5FDregister</B> <I>(H5FD_class_t *<VAR>cls</VAR>)</I> <DD><A NAME="IDX13"></A> </P> <P> The driver described by struct <VAR>cls</VAR> is registered with the library and an ID number for the driver is returned. </DL> </P> <P> The <CODE>H5FD_class_t</CODE> type is a struct with the following fields: </P> <DL COMPACT> <DT><CODE>const char *name</CODE> <DD> A pointer to a constant, null-terminated driver name to be used for debugging purposes. <DT><CODE>size_t fapl_size</CODE> <DD> The size in bytes of the file access mode structure or zero if the driver supplies a copy function or doesn't define the structure. <DT><CODE>void *(*fapl_copy)(const void *fapl)</CODE> <DD> An optional function which copies a driver-defined file access mode structure. This field takes precedence over <CODE>fm_size</CODE> when both are defined. <DT><CODE>void (*fapl_free)(void *fapl)</CODE> <DD> An optional function to free the driver-defined file access mode structure. If null, then the library calls the C <CODE>free</CODE> function to free the structure. <DT><CODE>size_t dxpl_size</CODE> <DD> The size in bytes of the data transfer mode structure or zero if the driver supplies a copy function or doesn't define the structure. <DT><CODE>void *(*dxpl_copy)(const void *dxpl)</CODE> <DD> An optional function which copies a driver-defined data transfer mode structure. This field takes precedence over <CODE>xm_size</CODE> when both are defined. <DT><CODE>void (*dxpl_free)(void *dxpl)</CODE> <DD> An optional function to free the driver-defined data transfer mode structure. If null, then the library calls the C <CODE>free</CODE> function to free the structure. <DT><CODE>H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl, haddr_t maxaddr)</CODE> <DD> The function which opens or creates a new file. <DT><CODE>herr_t (*close)(H5FD_t *file)</CODE> <DD> The function which ends access to a file. <DT><CODE>int (*cmp)(const H5FD_t *f1, const H5FD_t *f2)</CODE> <DD> An optional function to determine whether two open files have the same key. If this function is not present then the library assumes that two files will never be the same. <DT><CODE>int (*query)(const H5FD_t *f, unsigned long *flags)</CODE> <DD> An optional function to determine which library optimizations a driver can support. <DT><CODE>haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hsize_t size)</CODE> <DD> An optional function to allocate space in the file. <DT><CODE>herr_t (*free)(H5FD_t *file, H5FD_mem_t type, haddr_t addr, hsize_t size)</CODE> <DD> An optional function to free space in the file. <DT><CODE>haddr_t (*get_eoa)(H5FD_t *file)</CODE> <DD> A function to query how much of the format address space has been allocated. <DT><CODE>herr_t (*set_eoa)(H5FD_t *file, haddr_t)</CODE> <DD> A function to set the end of address space. <DT><CODE>haddr_t (*get_eof)(H5FD_t *file)</CODE> <DD> A function to return the current end-of-file marker value. <DT><CODE>herr_t (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, hsize_t size, void *buffer)</CODE> <DD> A function to read data from a file. <DT><CODE>herr_t (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, hsize_t size, const void *buffer)</CODE> <DD> A function to write data to a file. <DT><CODE>herr_t (*flush)(H5FD_t *file)</CODE> <DD> A function which flushes cached data to the file. <DT><CODE>H5FD_mem_t fl_map[H5FD_MEM_NTYPES]</CODE> <DD> An array which maps a file allocation request type to a free list. </DL> <P> <STRONG>Example:</STRONG> The sec2 driver would be registered as: </P> <PRE> static const H5FD_class_t H5FD_sec2_g = { "sec2", /*name */ MAXADDR, /*maxaddr */ NULL, /*sb_size */ NULL, /*sb_encode */ NULL, /*sb_decode */ 0, /*fapl_size */ NULL, /*fapl_get */ NULL, /*fapl_copy */ NULL, /*fapl_free */ 0, /*dxpl_size */ NULL, /*dxpl_copy */ NULL, /*dxpl_free */ H5FD_sec2_open, /*open */ H5FD_sec2_close, /*close */ H5FD_sec2_cmp, /*cmp */ H5FD_sec2_query, /*query */ NULL, /*alloc */ NULL, /*free */ H5FD_sec2_get_eoa, /*get_eoa */ H5FD_sec2_set_eoa, /*set_eoa */ H5FD_sec2_get_eof, /*get_eof */ H5FD_sec2_read, /*read */ H5FD_sec2_write, /*write */ H5FD_sec2_flush, /*flush */ H5FD_FLMAP_SINGLE, /*fl_map */ }; hid_t H5FD_sec2_init(void) { if (!H5FD_SEC2_g) { H5FD_SEC2_g = H5FDregister(&#38;H5FD_sec2_g); } return H5FD_SEC2_g; } </PRE> <P> A driver can be removed from the library by unregistering it </P> <P> <DL> <DT><U>Function:</U> herr_t <B>H5Dunregister</B> <I>(hid_t <VAR>driver</VAR>)</I> <DD><A NAME="IDX14"></A> Where <VAR>driver</VAR> is the ID number returned when the driver was registered. </DL> </P> <P> Unregistering a driver makes it unusable for creating new file access or data transfer property lists but doesn't affect any property lists or files that already use that driver. </P> <H3><A NAME="SECProgNote" HREF="#TOCProgNote">Programming Note for C++ Developers Using C Functions</A></H3> <p>If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally. </p> <p>Examples of this kind of routine include callbacks such as <code>H5Pset_elink_cb</code> and <code>H5Pset_type_conv_cb</code> and functions such as <code>H5Tconvert</code> and <code>H5Ewalk2</code>.</p> <p>Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ &ldquo;catch&rdquo; statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.</p> <H2><A NAME="SEC24" HREF="#TOC24">Querying Driver Information</A></H2> <P> <DL> <DT><U>Function:</U> void * <B>H5Pget_driver_data</B> <I>(hid_t <VAR>fapl</VAR>)</I> <DD><A NAME="IDX15"></A> <DT><U>Function:</U> void * <B>H5Pget_driver_data</B> <I>(hid_t <VAR>fxpl</VAR>)</I> <DD><A NAME="IDX16"></A> </P> <P> This function is intended to be used by driver functions, not applications. It returns a pointer directly into the file access property list <CODE><VAR>fapl</VAR></CODE> which is a copy of the driver's file access mode originally provided to the <CODE>H5Pset_driver</CODE> function. If its argument is a data transfer property list <CODE>fxpl</CODE> then it returns a pointer to the driver-specific data transfer information instead. </DL> </P> <H1><A NAME="SEC25" HREF="#TOC25">Miscellaneous</A></H1> <P> The various private <CODE>H5F_low_*</CODE> functions will be replaced by public <CODE>H5FD*</CODE> functions so they can be called from drivers. </P> <P> All private functions <CODE>H5F_addr_*</CODE> which operate on addresses will be renamed as public functions by removing the first underscore so they can be called by drivers. </P> <P> The <CODE>haddr_t</CODE> address data type will be passed by value throughout the library. The original intent was that this type would eventually be a union of file address types for the various drivers and may become quite large, but that was back when drivers were part of HDF5. It will become an alias for an unsigned integer type (32 or 64 bits depending on how the library was configured). </P> <P> The various <CODE>H5F*.c</CODE> driver files will be renamed <CODE>H5FD*.c</CODE> and each will have a corresponding header file. All driver functions except the initializer and API will be declared static. </P> <P> This documentation didn't cover optimization functions which would be useful to drivers like MPI-IO. Some drivers may be able to perform data pipeline operations more efficiently than HDF5 and need to be given a chance to override those parts of the pipeline. The pipeline would be designed to call various H5FD optimization functions at various points which return one of three values: the operation is not implemented by the driver, the operation is implemented but failed in a non-recoverable manner, the operation is implemented and succeeded. </P> <P> Various parts of HDF5 check the only the top-level file driver and do something special if it is the MPI-IO driver. However, we might want to be able to put the MPI-IO driver under other drivers such as the raw part of a split driver or under a debug driver whose sole purpose is to accumulate statistics as it passes all requests through to the MPI-IO driver. Therefore we will probably need a function which takes a format address and or object type and returns the driver which would have been used at the lowest level to process the request. </P> <P><HR><P> <H1>Footnotes</H1> <H3><A NAME="FOOT1" HREF="#DOCF1">(1)</A></H3> <P>The driver name is by convention and might not apply to drivers which are not distributed with HDF5. <H3><A NAME="FOOT2" HREF="#DOCF2">(2)</A></H3> <P>The access method also indicates how to translate the storage name to a storage server such as a file, network protocol, or memory. <H3><A NAME="FOOT3" HREF="#DOCF3">(3)</A></H3> <P>The term "<EM>file</EM> access property list" is a misnomer since storage isn't required to be a file. <H3><A NAME="FOOT4" HREF="#DOCF4">(4)</A></H3> <P>This function is overloaded to operate on data transfer property lists also, as described below. <H3><A NAME="FOOT5" HREF="#DOCF5">(5)</A></H3> <P>Read-only access is only appropriate when opening an existing file. <H3><A NAME="FOOT6" HREF="#DOCF6">(6)</A></H3> <P>For instance, writing data to one handle will cause the data to be immediately visible on the other handle. <H3><A NAME="FOOT7" HREF="#DOCF7">(7)</A></H3> <P>The ordering is arbitrary as long as it's consistent within a particular file driver. <H3><A NAME="FOOT8" HREF="#DOCF8">(8)</A></H3> <P>File access modes do not describe data, but rather describe how the HDF5 format address space is mapped to the underlying file(s). Thus, in general the mapping must be known before the file superblock can be read. However, the user usually knows enough about the mapping for the superblock to be readable and once the superblock is read the library can fill in the missing parts of the mapping. <P><HR><P> <?php include("../ed_libs/Footer2.htm"); ?> </BODY> </HTML> </div></div><!-- contents --> </div><!-- PageDoc --> </div><!-- doc-content --> <!-- start footer part --> <div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> <ul> <li class="footer">Generated by <a href="http://www.doxygen.org/index.html"> <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li> </ul> </div> </body> </html>