fd.c: Avoid gcc warning regarding fchdir().
[adu.git] / format.h
1 /*
2 * Copyright (C) 2008 Andre Noll <maan@tuebingen.mpg.de>
3 *
4 * Licensed under the GPL v2. For licencing details see COPYING.
5 */
6
7 /** \file format.h \brief Exported symbols from \p format.c. */
8
9 /** The possible types of format string directives (aka atoms). */
10 enum atom_type {
11 /** String, supports alignment and width. */
12 AT_STRING,
13 /** Used for user IDs, supports alignment and width. */
14 AT_ID,
15 /**
16 * Used for number of files/directories, supports alignment,
17 * width, unit.
18 */
19 AT_COUNT,
20 /**
21 * Used for number of bytes. Like \p AT_COUNT, but the unit is
22 * treated differently: By default, 1024 is used as the base,
23 * and low numbers get a "b" (bytes) appended which does not make
24 * sense for counters.
25 */
26 AT_SIZE
27 };
28
29 /**
30 * One format string directive.
31 *
32 * Each application must define its own set of valid atoms as an array
33 * of struct atom. The \ref parse_format_string() function takes a format
34 * string and the array of valid atoms and returns an opaque pointer to
35 * a struct \a format_info.
36 *
37 * At a later time the application may pass the \a format_info pointer
38 * together with the current value for each atom to \a format_items() which
39 * returns these values, formated according to the format string which has
40 * been passed to parse_format_string() previously.
41 *
42 * Usually, the application will call parse_format_string() only once, but
43 * format_items() many times.
44 */
45 struct atom {
46 /** The name of the directive. */
47 const char const *name;
48 /** Its type. */
49 enum atom_type type;
50 };
51
52 /**
53 * The current value of one atom.
54 *
55 * An array of this type, whose entries must match the array of valid atoms,
56 * may be passed to format_items() to obtain a formated string.
57 */
58 union atom_value {
59 /** Used for atoms of type string. */
60 char *string_value;
61 /** Used for atoms not of type string. */
62 long long unsigned num_value;
63 };
64
65 /**
66 * The details of this structure are only relevant to the functions in \p
67 * format.c.
68 */
69 struct format_info;
70
71 int parse_format_string(char *fmt, struct atom *atoms,
72 struct format_info **result);
73 char *format_items(struct format_info *info, union atom_value *values);
74 void free_format_info(struct format_info *info);