include/babeltrace/ctf-writer/writer.h

   1 #ifndef BABELTRACE_CTF_WRITER_WRITER_H
   2 #define BABELTRACE_CTF_WRITER_WRITER_H
   3
   4 /*
   5  * BabelTrace - CTF Writer: Writer
   6  *
   7  * Copyright 2013, 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   8  *
   9  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  10  *
  11  * Permission is hereby granted, free of charge, to any person obtaining a copy
  12  * of this software and associated documentation files (the "Software"), to deal
  13  * in the Software without restriction, including without limitation the rights
  14  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  15  * copies of the Software, and to permit persons to whom the Software is
  16  * furnished to do so, subject to the following conditions:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  21  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  22  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  23  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  24  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  25  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  26  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  27  * SOFTWARE.
  28  *
  29  * The Common Trace Format (CTF) Specification is available at
  30  * http://www.efficios.com/ctf
  31  */
  32
  33 #include <babeltrace/ctf-ir/field-types.h>
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 struct bt_ctf_writer;
  40 struct bt_ctf_stream;
  41 struct bt_ctf_stream_class;
  42 struct bt_ctf_clock;
  43
  44 /*
  45  * bt_ctf_writer_create: create a writer instance.
  46  *
  47  * Allocate a new writer that will produce a trace in the given path.
  48  * The creation of a writer sets its reference count to 1.
  49  *
  50  * @param path Path to the trace's containing folder (string is copied).
  51  *
  52  * Returns an allocated writer on success, NULL on error.
  53  */
  54 extern struct bt_ctf_writer *bt_ctf_writer_create(const char *path);
  55
  56 /*
  57  * bt_ctf_writer_get_trace: Get a writer's associated trace.
  58  *
  59  * @param writer Writer instance.
  60  *
  61  * Return the writer's associated instance, NULL on error.
  62  */
  63 extern struct bt_ctf_trace *bt_ctf_writer_get_trace(
  64                 struct bt_ctf_writer *writer);
  65
  66 /*
  67  * bt_ctf_writer_create_stream: create a stream instance.
  68  *
  69  * Allocate a new stream instance and register it to the writer. The creation of
  70  * a stream sets its reference count to 1.
  71  *
  72  * @param writer Writer instance.
  73  * @param stream_class Stream class to instantiate.
  74  *
  75  * Returns an allocated stream on success, NULL on error.
  76  */
  77 extern struct bt_ctf_stream *bt_ctf_writer_create_stream(
  78                 struct bt_ctf_writer *writer,
  79                 struct bt_ctf_stream_class *stream_class);
  80
  81 /*
  82  * bt_ctf_writer_add_environment_field: add an environment field to the trace.
  83  *
  84  * Add an environment field to the trace. The name and value parameters are
  85  * copied.
  86  *
  87  * @param writer Writer instance.
  88  * @param name Name of the environment field (will be copied).
  89  * @param value Value of the environment field (will be copied).
  90  *
  91  * Returns 0 on success, a negative value on error.
  92  */
  93 extern int bt_ctf_writer_add_environment_field(struct bt_ctf_writer *writer,
  94                 const char *name,
  95                 const char *value);
  96
  97 /*
  98  * bt_ctf_writer_add_clock: add a clock to the trace.
  99  *
 100  * Add a clock to the trace. Clocks assigned to stream classes must be
 101  * registered to the writer.
 102  *
 103  * @param writer Writer instance.
 104  * @param clock Clock to add to the trace.
 105  *
 106  * Returns 0 on success, a negative value on error.
 107  */
 108 extern int bt_ctf_writer_add_clock(struct bt_ctf_writer *writer,
 109                 struct bt_ctf_clock *clock);
 110
 111 /*
 112  * bt_ctf_writer_get_metadata_string: get meta-data string.
 113  *
 114  * Get the trace's TSDL meta-data. The caller assumes the ownership of the
 115  * returned string.
 116  *
 117  * @param writer Writer instance.
 118  *
 119  * Returns the metadata string on success, NULL on error.
 120  */
 121 extern char *bt_ctf_writer_get_metadata_string(struct bt_ctf_writer *writer);
 122
 123 /*
 124  * bt_ctf_writer_flush_metadata: flush the trace's metadata to disk.
 125  *
 126  * Flush the trace's metadata to the metadata file. Note that the metadata will
 127  * be flushed automatically when the Writer instance is released (last call to
 128  * bt_ctf_writer_put).
 129  *
 130  * @param writer Writer instance.
 131  */
 132 extern void bt_ctf_writer_flush_metadata(struct bt_ctf_writer *writer);
 133
 134 /*
 135  * bt_ctf_writer_set_byte_order: set a field type's byte order.
 136  *
 137  * Set the trace's byte order. Defaults to the host machine's endianness.
 138  *
 139  * @param writer Writer instance.
 140  * @param byte_order Trace's byte order.
 141  *
 142  * Returns 0 on success, a negative value on error.
 143  *
 144  * Note: byte_order must not be BT_CTF_BYTE_ORDER_NATIVE since, according
 145  * to the CTF specification, is defined as "the byte order described in the
 146  * trace description".
 147  */
 148 extern int bt_ctf_writer_set_byte_order(struct bt_ctf_writer *writer,
 149                 enum bt_ctf_byte_order byte_order);
 150
 151 /*
 152  * bt_ctf_writer_get and bt_ctf_writer_put: increment and decrement the
 153  * writer's reference count.
 154  *
 155  * You may also use bt_ctf_get() and bt_ctf_put() with writer objects.
 156  *
 157  * These functions ensure that the writer won't be destroyed while it
 158  * is in use. The same number of get and put (plus one extra put to
 159  * release the initial reference done at creation) have to be done to
 160  * destroy a writer.
 161  *
 162  * When the writer's reference count is decremented to 0 by a
 163  * bt_ctf_writer_put, the writer is freed.
 164  *
 165  * @param writer Writer instance.
 166  */
 167 extern void bt_ctf_writer_get(struct bt_ctf_writer *writer);
 168 extern void bt_ctf_writer_put(struct bt_ctf_writer *writer);
 169
 170 #ifdef __cplusplus
 171 }
 172 #endif
 173
 174 #endif /* BABELTRACE_CTF_WRITER_WRITER_H */