← Back to branch summary

~ubuntu-branches/ubuntu/edgy/rpm/edgy

« back to all changes in this revision

Viewing changes to lib/hdrproto.h

  • Committer: Bazaar Package Importer
  • Author(s): Joey Hess
  • Date: 2002-01-22 20:56:57 UTC
  • Revision ID: james.westby@ubuntu.com-20020122205657-l74j50mr9z8ofcl5
Tags: upstream-4.0.3
Import upstream version 4.0.3

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/hdrproto.h
 
1
#ifndef H_HDRPROTO
 
2
#define H_HDRPROTO
 
3
 
 
4
/** \ingroup header
 
5
 * \file lib/hdrproto.h
 
6
 */
 
7
 
 
8
#ifdef __cplusplus
 
9
extern "C" {
 
10
#endif
 
11
 
 
12
/** \ingroup header
 
13
 * Create new (empty) header instance.
 
14
 * @return              header
 
15
 */
 
16
Header headerNew(void)  /*@*/;
 
17
 
 
18
/** \ingroup header
 
19
 * Dereference a header instance.
 
20
 * @param h             header
 
21
 * @return              NULL always
 
22
 */
 
23
/*@null@*/ Header headerFree( /*@null@*/ /*@killref@*/ Header h)
 
24
        /*@modifies h @*/;
 
25
 
 
26
/** \ingroup header
 
27
 * Reference a header instance.
 
28
 * @param h             header
 
29
 * @return              referenced header instance
 
30
 */
 
31
Header headerLink(Header h)
 
32
        /*@modifies h @*/;
 
33
 
 
34
/*@-exportlocal@*/
 
35
/** \ingroup header
 
36
 * Sort tags in header.
 
37
 * @param h             header
 
38
 */
 
39
void headerSort(Header h)
 
40
        /*@modifies h @*/;
 
41
 
 
42
/** \ingroup header
 
43
 * Restore tags in header to original ordering.
 
44
 * @param h             header
 
45
 */
 
46
void headerUnsort(Header h)
 
47
        /*@modifies h @*/;
 
48
/*@=exportlocal@*/
 
49
 
 
50
/** \ingroup header
 
51
 * Return size of on-disk header representation in bytes.
 
52
 * @param h             header
 
53
 * @param magicp        include size of 8 bytes for (magic, 0)?
 
54
 * @return              size of on-disk header
 
55
 */
 
56
unsigned int headerSizeof(/*@null@*/ Header h, enum hMagic magicp)
 
57
        /*@modifies h @*/;
 
58
 
 
59
/** \ingroup header
 
60
 * Convert header to on-disk representation.
 
61
 * @param h             header (with pointers)
 
62
 * @return              on-disk header blob (i.e. with offsets)
 
63
 */
 
64
/*@only@*/ /*@null@*/ void * headerUnload(Header h)
 
65
        /*@modifies h @*/;
 
66
 
 
67
/** \ingroup header
 
68
 * Convert header to on-disk representation, and then reload.
 
69
 * This is used to insure that all header data is in one chunk.
 
70
 * @param h             header (with pointers)
 
71
 * @param tag           region tag
 
72
 * @return              on-disk header (with offsets)
 
73
 */
 
74
/*@null@*/ Header headerReload(/*@only@*/ Header h, int tag)
 
75
        /*@modifies h @*/;
 
76
 
 
77
/** \ingroup header
 
78
 * Duplicate a header.
 
79
 * @param h             header
 
80
 * @return              new header instance
 
81
 */
 
82
/*@null@*/ Header headerCopy(Header h)
 
83
        /*@modifies h @*/;
 
84
 
 
85
/** \ingroup header
 
86
 * Convert header to in-memory representation.
 
87
 * @param uh            on-disk header blob (i.e. with offsets)
 
88
 * @return              header
 
89
 */
 
90
/*@-exportlocal@*/
 
91
/*@null@*/ Header headerLoad(/*@kept@*/ void * uh)
 
92
        /*@modifies uh @*/;
 
93
/*@=exportlocal@*/
 
94
 
 
95
/** \ingroup header
 
96
 * Write (with unload) header to file handle.
 
97
 * @param fd            file handle
 
98
 * @param h             header
 
99
 * @param magicp        prefix write with 8 bytes of (magic, 0)?
 
100
 * @return              0 on success, 1 on error
 
101
 */
 
102
int headerWrite(FD_t fd, /*@null@*/ Header h, enum hMagic magicp)
 
103
        /*@modifies fd, h, fileSystem @*/;
 
104
 
 
105
/** \ingroup header
 
106
 * Make a copy and convert header to in-memory representation.
 
107
 * @param uh            on-disk header blob (i.e. with offsets)
 
108
 * @return              header
 
109
 */
 
110
/*@null@*/ Header headerCopyLoad(const void * uh)
 
111
        /*@*/;
 
112
 
 
113
/** \ingroup header
 
114
 * Read (and load) header from file handle.
 
115
 * @param fd            file handle
 
116
 * @param magicp        read (and verify) 8 bytes of (magic, 0)?
 
117
 * @return              header (or NULL on error)
 
118
 */
 
119
/*@null@*/ Header headerRead(FD_t fd, enum hMagic magicp)
 
120
        /*@modifies fd, fileSystem @*/;
 
121
 
 
122
/** \ingroup header
 
123
 * Check if tag is in header.
 
124
 * @param h             header
 
125
 * @param tag           tag
 
126
 * @return              1 on success, 0 on failure
 
127
 */
 
128
int headerIsEntry(/*@null@*/Header h, int_32 tag)
 
129
        /*@*/;
 
130
 
 
131
/** \ingroup header
 
132
 * Retrieve tag value.
 
133
 * Will never return RPM_I18NSTRING_TYPE! RPM_STRING_TYPE elements with
 
134
 * RPM_I18NSTRING_TYPE equivalent entries are translated (if HEADER_I18NTABLE
 
135
 * entry is present).
 
136
 *
 
137
 * @param h             header
 
138
 * @param tag           tag
 
139
 * @retval type         address of tag value data type (or NULL)
 
140
 * @retval p            address of pointer to tag value(s) (or NULL)
 
141
 * @retval c            address of number of values (or NULL)
 
142
 * @return              1 on success, 0 on failure
 
143
 */
 
144
int headerGetEntry(Header h, int_32 tag,
 
145
                        /*@null@*/ /*@out@*/ hTYP_t type,
 
146
                        /*@null@*/ /*@out@*/ void ** p,
 
147
                        /*@null@*/ /*@out@*/ hCNT_t c)
 
148
        /*@modifies *type, *p, *c @*/;
 
149
 
 
150
/** \ingroup header
 
151
 * Retrieve tag value using header internal array.
 
152
 * Get an entry using as little extra RAM as possible to return the tag value.
 
153
 * This is only an issue for RPM_STRING_ARRAY_TYPE.
 
154
 *
 
155
 * @param h             header
 
156
 * @param tag           tag
 
157
 * @retval type         address of tag value data type (or NULL)
 
158
 * @retval p            address of pointer to tag value(s) (or NULL)
 
159
 * @retval c            address of number of values (or NULL)
 
160
 * @return              1 on success, 0 on failure
 
161
 */
 
162
int headerGetEntryMinMemory(Header h, int_32 tag,
 
163
                        /*@null@*/ /*@out@*/ hTYP_t type,
 
164
                        /*@null@*/ /*@out@*/ hPTR_t * p,
 
165
                        /*@null@*/ /*@out@*/ hCNT_t c)
 
166
        /*@modifies *type, *p, *c @*/;
 
167
 
 
168
/** \ingroup header
 
169
 * Add tag to header.
 
170
 * Duplicate tags are okay, but only defined for iteration (with the
 
171
 * exceptions noted below). While you are allowed to add i18n string
 
172
 * arrays through this function, you probably don't mean to. See
 
173
 * headerAddI18NString() instead.
 
174
 *
 
175
 * @param h             header
 
176
 * @param tag           tag
 
177
 * @param type          tag value data type
 
178
 * @param p             pointer to tag value(s)
 
179
 * @param c             number of values
 
180
 * @return              1 on success, 0 on failure
 
181
 */
 
182
/*@mayexit@*/
 
183
int headerAddEntry(Header h, int_32 tag, int_32 type, const void * p, int_32 c)
 
184
        /*@modifies h @*/;
 
185
 
 
186
/** \ingroup header
 
187
 * Append element to tag array in header.
 
188
 * Appends item p to entry w/ tag and type as passed. Won't work on
 
189
 * RPM_STRING_TYPE. Any pointers into header memory returned from
 
190
 * headerGetEntryMinMemory() for this entry are invalid after this
 
191
 * call has been made!
 
192
 *
 
193
 * @param h             header
 
194
 * @param tag           tag
 
195
 * @param type          tag value data type
 
196
 * @param p             pointer to tag value(s)
 
197
 * @param c             number of values
 
198
 * @return              1 on success, 0 on failure
 
199
 */
 
200
int headerAppendEntry(Header h, int_32 tag, int_32 type,
 
201
                const void * p, int_32 c)
 
202
        /*@modifies h @*/;
 
203
 
 
204
/** \ingroup header
 
205
 * Add or append element to tag array in header.
 
206
 * @todo Arg "p" should have const.
 
207
 * @param h             header
 
208
 * @param tag           tag
 
209
 * @param type          tag value data type
 
210
 * @param p             pointer to tag value(s)
 
211
 * @param c             number of values
 
212
 * @return              1 on success, 0 on failure
 
213
 */
 
214
int headerAddOrAppendEntry(Header h, int_32 tag, int_32 type,
 
215
                const void * p, int_32 c)
 
216
        /*@modifies h @*/;
 
217
 
 
218
/** \ingroup header
 
219
 * Add locale specific tag to header.
 
220
 * A NULL lang is interpreted as the C locale. Here are the rules:
 
221
 * \verbatim
 
222
 *      - If the tag isn't in the header, it's added with the passed string
 
223
 *         as new value.
 
224
 *      - If the tag occurs multiple times in entry, which tag is affected
 
225
 *         by the operation is undefined.
 
226
 *      - If the tag is in the header w/ this language, the entry is
 
227
 *         *replaced* (like headerModifyEntry()).
 
228
 * \endverbatim
 
229
 * This function is intended to just "do the right thing". If you need
 
230
 * more fine grained control use headerAddEntry() and headerModifyEntry().
 
231
 *
 
232
 * @param h             header
 
233
 * @param tag           tag
 
234
 * @param string        tag value
 
235
 * @param lang          locale
 
236
 * @return              1 on success, 0 on failure
 
237
 */
 
238
int headerAddI18NString(Header h, int_32 tag, const char * string,
 
239
                const char * lang)
 
240
        /*@modifies h @*/;
 
241
 
 
242
/** \ingroup header
 
243
 * Modify tag in header.
 
244
 * If there are multiple entries with this tag, the first one gets replaced.
 
245
 * @param h             header
 
246
 * @param tag           tag
 
247
 * @param type          tag value data type
 
248
 * @param p             pointer to tag value(s)
 
249
 * @param c             number of values
 
250
 * @return              1 on success, 0 on failure
 
251
 */
 
252
int headerModifyEntry(Header h, int_32 tag, int_32 type,
 
253
                        const void * p, int_32 c)
 
254
        /*@modifies h @*/;
 
255
 
 
256
/** \ingroup header
 
257
 * Delete tag in header.
 
258
 * Removes all entries of type tag from the header, returns 1 if none were
 
259
 * found.
 
260
 *
 
261
 * @param h             header
 
262
 * @param tag           tag
 
263
 * @return              0 on success, 1 on failure (INCONSISTENT)
 
264
 */
 
265
int headerRemoveEntry(Header h, int_32 tag)
 
266
        /*@modifies h @*/;
 
267
 
 
268
/** \ingroup header
 
269
 * Return formatted output string from header tags.
 
270
 * The returned string must be free()d.
 
271
 *
 
272
 * @param h             header
 
273
 * @param fmt           format to use
 
274
 * @param tags          array of tag name/value pairs
 
275
 * @param extensions    chained table of formatting extensions.
 
276
 * @retval errmsg       error message (if any)
 
277
 * @return              formatted output string (malloc'ed)
 
278
 */
 
279
/*@only@*/ char * headerSprintf(Header h, const char * fmt,
 
280
                     const struct headerTagTableEntry_s * tags,
 
281
                     const struct headerSprintfExtension_s * extensions,
 
282
                     /*@null@*/ /*@out@*/ errmsg_t * errmsg)
 
283
        /*@modifies *errmsg @*/;
 
284
 
 
285
/** \ingroup header
 
286
 * Duplicate tag values from one header into another.
 
287
 * @param headerFrom    source header
 
288
 * @param headerTo      destination header
 
289
 * @param tagstocopy    array of tags that are copied
 
290
 */
 
291
void headerCopyTags(Header headerFrom, Header headerTo, hTAG_t tagstocopy)
 
292
        /*@modifies headerTo @*/;
 
293
 
 
294
/** \ingroup header
 
295
 * Destroy header tag iterator.
 
296
 * @param hi            header tag iterator
 
297
 * @return              NULL always
 
298
 */
 
299
/*@null@*/ HeaderIterator headerFreeIterator(/*@only@*/ HeaderIterator hi)
 
300
        /*@modifies hi @*/;
 
301
 
 
302
/** \ingroup header
 
303
 * Create header tag iterator.
 
304
 * @param h             header
 
305
 * @return              header tag iterator
 
306
 */
 
307
HeaderIterator headerInitIterator(Header h)
 
308
        /*@modifies h */;
 
309
 
 
310
/** \ingroup header
 
311
 * Return next tag from header.
 
312
 * @param hi            header tag iterator
 
313
 * @retval tag          address of tag
 
314
 * @retval type         address of tag value data type
 
315
 * @retval p            address of pointer to tag value(s)
 
316
 * @retval c            address of number of values
 
317
 * @return              1 on success, 0 on failure
 
318
 */
 
319
int headerNextIterator(HeaderIterator hi,
 
320
                /*@null@*/ /*@out@*/ hTAG_t tag,
 
321
                /*@null@*/ /*@out@*/ hTYP_t type,
 
322
                /*@null@*/ /*@out@*/ hPTR_t * p,
 
323
                /*@null@*/ /*@out@*/ hCNT_t c)
 
324
        /*@modifies hi, *tag, *type, *p, *c @*/;
 
325
 
 
326
#ifdef __cplusplus
 
327
}
 
328
#endif
 
329
 
 
330
#endif  /* H_HDRPROTO */