← Back to branch summary

~ubuntu-branches/ubuntu/wily/luatex/wily

« back to all changes in this revision

Viewing changes to source/texk/web2c/luatexdir/zziplib/docs/zzip-extras.htm

  • Committer: Bazaar Package Importer
  • Author(s): Norbert Preining
  • Date: 2010-04-29 00:47:19 UTC
  • mfrom: (1.1.10 upstream)
  • Revision ID: james.westby@ubuntu.com-20100429004719-o42etkqe90n97b9e
Tags: 0.60.1-1
* new upstream release, adapt build-script patch
* disable patch: upstream-epstopdf_cc_no_xpdf_patching, included upstream
* disable patch: libpoppler-0.12, not needed anymore

Show diffs side-by-side

added added

removed removed

Lines of Context:
source/texk/web2c/luatexdir/zziplib/docs/zzip-extras.htm
1
 
<section><date> 20. July 2002 </date>
2
 
<h2> ZZIP API extras </h2>             The check/init API description.
3
 
 
4
 
<!--border--> 
5
 
 
6
 
<section>
7
 
<h3> Extras </h3>
8
 
 
9
 
<P>
10
 
  The next requests circulated around other file-extensions to 
11
 
  automagically look inside filetypes that have zip-format too but 
12
 
  carry other fileextensions - most famous might be the ".PK3"
13
 
  files of ID's Quake game. There have been a number of these
14
 
  requests and in a lot of cases it dawned to me that those guys
15
 
  may have overlooked the zzip_dir_open functions to travel
16
 
  through documents of zipformat under any name - that is that the
17
 
  "magic" was not actually needed but they just wanted to read
18
 
  files in zipformat with the zziplib.
19
 
</P>
20
 
 
21
 
<P>
22
 
  Other requests circulated around encryption but I did reject
23
 
  those bluntly, always. Instead there have been always examples
24
 
  for doing some obfuscation around the zip-format so that the
25
 
  stock zip/unzip tools do not recognize them but a game
26
 
  software developer can pack/unpack his AI scripts and bitmaps
27
 
  into such a zipformat-like file.
28
 
</P>
29
 
 
30
 
<P>
31
 
  After some dead-end patches (being shipped along with the
32
 
  zziplib as configure-time compile-options - greetings to
33
 
  Lutz Sammer and Andreas Schiffler), the general approach 
34
 
  of _ext_io came up, and finally implemented (greetings go
35
 
  to Mike Nordell). The _open()-calls do now each have a
36
 
  cousin of _open_ext_io() with two/three additional arguments
37
 
  being a set of extensions to loop through our magic testing,
38
 
  a callback-handler plugin-table for obfuscation-means, 
39
 
  and (often) a bit-mask for extra-options - this bitmask even
40
 
  has "PREFERZIP" and "ONLYZIP" options to skip the real-file
41
 
  test magic in those <code>zzip_*open</code> functions.
42
 
</P>
43
 
 
44
 
<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
45
 
  <tr><td width=50%> zzip_open(name,flags) </td>
46
 
      <td width=50%> zzip_open_ext_io(name,flags,mode,ext,io) </td></tr>
47
 
  <tr><td width=50%> zzip_opendir(name) </td>
48
 
      <td width=50%> zzip_opendir_ext_io(name,mode,ext,io) </td></tr>
49
 
  <tr><td width=50%> zzip_dir_open(name,errp) </td>
50
 
      <td width=50%> zzip_dir_open_ext_io(name,errp,ext,io) </td></tr>
51
 
  <tr><td width=50%> zzip_dir_fdopen(fd,errp) </td>
52
 
      <td width=50%> zzip_dir_fdopen_ext_io(fd,errp,ext,io) </td></tr>
53
 
  <tr><td width=50%> zzip_file_open(dir,name,mode) </td>
54
 
      <td width=50%> zzip_file_open_ext_io(dir,name,mode,ext,io) </td></tr>
55
 
</table></td></tr></table>
56
 
 
57
 
<P>
58
 
  Oh, and note that the mode,ext,io extras are memorized 
59
 
  in the respecitive ZZIP_DIR handle attached, so each
60
 
  of the other calls like <code>zzip_file_open()</code>
61
 
  and <code>zzip_read()</code> will be using them. There
62
 
  are a few helper routines to help setup a new io-plugin
63
 
  where the init_io will currently just memcopy the
64
 
  default_io entries into the user-supplied plugin-struct.
65
 
</P>
66
 
 
67
 
<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
68
 
  <tr><td width=50%> zzip_init_io </td>
69
 
      <td width=50%> the recommended way to do things </td></tr>
70
 
  <tr><td width=50%> zzip_get_default_io </td>
71
 
      <td width=50%> used internally whenever you supply a null
72
 
                     for the io-argument of a _ext_io()-call </td></tr>
73
 
  <tr><td width=50%> zzip_get_default_ext </td>
74
 
      <td width=50%> used internally but not exported </td></tr>
75
 
</table></td></tr></table>
76
 
 
77
 
 
78
 
<P>
79
 
  And last some stdio-like replacements were build but these
80
 
  happen to be actually just small wrappers around the other
81
 
  posix-like magic-calls. It just offers some convenience
82
 
  since wrappers like "SDL_rwops" tend to use a stringised
83
 
  open-mode - and I took the occasion to fold the zzip-bits
84
 
  for the _ext_io-calls right in there recognized via 
85
 
  special extensions to the openmode-string of zzip_fopen().
86
 
</P>
87
 
 
88
 
<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
89
 
  <tr><td width=50%> zzip_fopen </td>
90
 
      <td width=50%> convert stringmode and call zzip_open_ext_io </td></tr>
91
 
  <tr><td width=50%> zzip_fread </td>
92
 
      <td width=50%> slower way to say zzip_read </td></tr>
93
 
  <tr><td width=50%> zzip_fclose </td>
94
 
      <td width=50%> a synonym of zzip_close </td></tr>
95
 
</table></td></tr></table>
96
 
 
97
 
<P>
98
 
  For some reason, people did need the full set of function-calls()
99
 
  to be working on zzip-wrappers too, so here they are - if the
100
 
  ZZIP_FILE instance did wrap a real file, then the real posix-call
101
 
  will be used, otherwise it is simulated on the compressed stream
102
 
  with a zip-contained file - especially <code>seek()</code> can be 
103
 
  a slow operation:
104
 
  if the new point is later then just read out more bytes till we
105
 
  hit that position but if it is an earlier point then rewind to the
106
 
  beginning of the compressed data and start reading/decompression
107
 
  until the position is met.
108
 
</P>
109
 
 
110
 
<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
111
 
  <tr><td width=50%> zzip_rewind </td>
112
 
      <td width=50%> magic for rewind() </td></tr>
113
 
  <tr><td width=50%> zzip_tell </td>
114
 
      <td width=50%> magic for tell() </td></tr>
115
 
  <tr><td width=50%> zzip_seek </td>
116
 
      <td width=50%> magic for seek() </td></tr>
117
 
</table></td></tr></table>
118
 
 
119
 
<P>
120
 
  And last not least, there are few informative functions to
121
 
  use function-calls to read parts of the opaque structures
122
 
  of zzip-objects and their zzip-factory.
123
 
</P>
124
 
 
125
 
<table cellpadding=10 width=100%><tr><td><table border=1 width=100%>
126
 
  <tr><td width=50%> zzip_dir_stat </td>
127
 
      <td width=50%> a stat()-like thing on a file within a ZZIP_DIR </td></tr>
128
 
  <tr><td width=50%> zzip_dir_real </td>
129
 
      <td width=50%> check if ZZIP_DIR wraps a stat'able posix-dirent</td></tr>
130
 
  <tr><td width=50%> zzip_file_real </td>
131
 
      <td width=50%> check if ZZIP_FILE wraps a stat'able posix-file </td></tr>
132
 
  <tr><td width=50%> zzip_realdir </td>
133
 
      <td width=50%> if zzip_dir_real then return the posix-dirent </td></tr>
134
 
  <tr><td width=50%> zzip_realfd </td>
135
 
      <td width=50%> if zzip_file_real then return the posix-file </td></tr>
136
 
  <tr><td width=50%> zzip_dirhandle </td>
137
 
      <td width=50%> the attached ZZIP_DIR of compressed ZZIP_FILE </td></tr>
138
 
  <tr><td width=50%> zzip_dirfd </td>
139
 
      <td width=50%> the attached posix-file of ZZIP_DIR zip-file </td></tr>
140
 
  <tr><td width=50%> zzip_set_error </td>
141
 
      <td width=50%> set the last ZZIP_DIR error-code </td></tr>
142
 
  <tr><td width=50%> zzip_error </td>
143
 
      <td width=50%> get the last ZZIP_DIR error-code </td></tr>
144
 
  <tr><td width=50%> zzip_strerror </td>
145
 
      <td width=50%> convert a zzip_error into a readable string </td></tr>
146
 
  <tr><td width=50%> zzip_strerror_of </td>
147
 
      <td width=50%> combine both above zzip_strerror of zzip_error </td></tr>
148
 
  <tr><td width=50%> zzip_errno </td>
149
 
      <td width=50%> helper to wrap a zzip-error to a posix-errno </td></tr>
150
 
  <tr><td width=50%> zzip_compr_str </td>
151
 
      <td width=50%> helper to wrap a compr-number to a readable string
152
 
                     </td></tr>
153
 
  <tr><td width=50%> zzip_dir_free </td>
154
 
      <td width=50%> internally called by zzip_dir_close if the ref-count 
155
 
                     of the ZZIP_DIR has gone zero</td></tr>
156
 
  <tr><td width=50%> zzip_freopen </td>
157
 
      <td width=50%> to reuse the ZZIP_DIR from another ZZIP_FILE so it does
158
 
                     not need to be parsed again </td></tr>
159
 
  <tr><td width=50%> zzip_open_shared_io </td>
160
 
      <td width=50%> the ext/io cousin but it does not close the old ZZIP_FILE
161
 
                     and instead just shares the ZZIP_DIR if possible</td></tr>
162
 
</table></td></tr></table>
163
 
 
164
 
</section></section>