/usr/include/jose/io.h is in libjose-dev 10-2build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | /* vim: set tabstop=8 shiftwidth=4 softtabstop=4 expandtab smarttab colorcolumn=80: */
/*
* Copyright 2017 Red Hat, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* \brief IO Chaining
* \defgroup jose_io IO
* @{
*/
#pragma once
#include "cfg.h"
#include <stdbool.h>
#include <stdio.h>
#ifdef DOXYGEN
/**
* Defines a jose_io_t which calls jose_io_decref() at end of scope.
*
* For example:
*
* void foo() {
* uint8_t *buf = NULL;
* size_t len = 0;
* jose_io_auto_t *io = jose_io_malloc(NULL, &buf, &len);
* // jose_io_decref() implicitly called
* }
*/
typedef jose_io_t jose_io_auto_t;
/**
* The interface for chained IO.
*
* \see jose_io_malloc()
* \see jose_io_buffer()
* \see jose_io_file()
* \see jose_io_multiplex()
* \see jose_b64_enc_io()
* \see jose_b64_dec_io()
* \see jose_jws_sig_io()
* \see jose_jws_ver_io()
* \see jose_jwe_dec_io()
* \see jose_jwe_dec_cek_io()
* \see jose_jwe_enc_io()
* \see jose_jwe_enc_cek_io()
*/
typedef struct {
/**
* Pushes data into the IO chain.
*
* \param io The jose_io_t entity you are using.
* \param in The input buffer.
* \param len The length of the data in the input buffer.
* \return Returns true if all data was consumed, otherwise false.
*/
bool (*feed)(jose_io_t *io, const void *in, size_t len);
/**
* Completes the IO chain.
*
* Any data stored in internal buffers will be flushed.
*
* \param io The jose_io_t entity you are using.
* \return Returns true if flushing was successful, otherwise false.
*/
bool (*done)(jose_io_t *io);
} jose_io_t;
#else
#define jose_io_auto_t jose_io_t __attribute__((cleanup(jose_io_auto)))
typedef struct jose_io jose_io_t;
struct jose_io {
size_t refs;
bool (*feed)(jose_io_t *io, const void *in, size_t len);
bool (*done)(jose_io_t *io);
void (*free)(jose_io_t *io); /* Don't call this. Use jose_io_decref(). */
};
#endif
void
jose_io_auto(jose_io_t **io);
/**
* Increases the reference count of an IO object.
*
* This function always succeeds.
*
* \param io The jose_io_t entity you are using.
* \return The value of \p io (for convenience).
*/
jose_io_t *
jose_io_incref(jose_io_t *io);
/**
* Decreases the reference count of an IO object.
*
* When the reference count reaches zero, io->free() is called.
*
* \param io The jose_io_t entity you are using.
*/
void
jose_io_decref(jose_io_t *io);
/**
* Creates a new IO object which collects data into a dynamic buffer.
*
* The dynamic buffer is allocated into the \p buf pointer you provided and
* the length of the buffer is stored in \p len. The pointer referenced by
* \p buf must remain valid for the entire duration of the returned IO object.
*
* The default behavior is for the IO object to zero and free the buffer when
* it is freed. This means that, by default, you own the buffer pointer but
* the buffer itself is owned by the IO object. You can, however, steal the
* buffer by setting the buffer pointer to NULL.
*
* \see jose_io_malloc_steal()
* \param cfg The configuration context (optional).
* \param buf A buffer pointer pointer.
* \param len A pointer to the length of the buffer.
* \return The new IO object or NULL on error.
*/
jose_io_t *
jose_io_malloc(jose_cfg_t *cfg, void **buf, size_t *len);
/**
* Steals the buffer created by the jose_io_malloc() IO object.
*
* This convenience function simply returns the value of \p *buf and then sets
* \p *buf to NULL.
*
* \see jose_io_malloc()
* \param buf A pointer to the buffer pointer.
* \return The value of \p *buf before it is set to NULL.
*/
void *
jose_io_malloc_steal(void **buf);
/**
* Creates a new IO object which collects data into a static buffer.
*
* The size of \p buf MUST be specified in the variable pointed to by \p len.
* This will be the maximum data written. However, after the function returns,
* the variable pointed to by \p len will contain the current length of data in
* the buffer.
*
* Unlike jose_io_malloc(), you own the buffer and it is not zeroed or freed
* when the IO object is freed.
*
* \param cfg The configuration context (optional).
* \param buf A buffer pointer.
* \param len A pointer to the length of the buffer.
* \return The new IO object or NULL on error.
*/
jose_io_t *
jose_io_buffer(jose_cfg_t *cfg, void *buf, size_t *len);
/**
* Creates a new IO object which writes data into a FILE.
*
* This function DOES NOT take ownership of the FILE. You are still responsible
* for calling fclose() at the appropriate time.
*
* \param cfg The configuration context (optional).
* \param file The output file which MUST be opened for writing or appending.
* \return The new IO object or NULL on error.
*/
jose_io_t *
jose_io_file(jose_cfg_t *cfg, FILE *file);
/**
* Creates a new IO object which multiplexes data into multiple IO objects.
*
* If \p all is true, the success of all \p nexts is required. Otherwise,
* all but one of the \p nexts can fail before the error is propagated upward.
*
* \param cfg The configuration context (optional).
* \param nexts A NULL-terminated array of IO object pointers.
* \param all Whether or not the success of all \p nexts is required.
* \return The new IO object or NULL on error.
*/
jose_io_t *
jose_io_multiplex(jose_cfg_t *cfg, jose_io_t **nexts, bool all);
/** @} */
|