This file is indexed.

/usr/include/fstrm/writer.h is in libfstrm-dev 0.3.0-1build1.

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
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
/*
 * Copyright (c) 2014 by Farsight Security, 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.
 */

#ifndef FSTRM_WRITER_H
#define FSTRM_WRITER_H

/**
 * \defgroup fstrm_writer fstrm_writer
 *
 * `fstrm_writer` is an interface for writing Frame Streams data into a byte
 * stream. The underlying byte stream I/O operations are abstracted by the
 * \ref fstrm_rdwr interface. Thus, the `fstrm_writer` interface can be used to
 * write Frame Streams data to any type of output whose read/write operations
 * are wrapped by an `fstrm_rdwr` object.
 *
 * Some basic `fstrm_writer` implementations are already provided in the `fstrm`
 * library. See fstrm_file_writer_init() for an implementation that writes to
 * a regular file and fstrm_unix_writer_init() for an implementation that writes
 * to a Unix socket.
 *
 * @{
 */

/**
 * Initialize an `fstrm_writer_options` object.
 *
 * \return
 *	`fstrm_writer_options` object.
 */
struct fstrm_writer_options *
fstrm_writer_options_init(void);

/**
 * Destroy an `fstrm_writer_options` object.
 *
 * \param wopt
 *	Pointer to `fstrm_writer_options` object.
 */
void
fstrm_writer_options_destroy(
	struct fstrm_writer_options **wopt);

/**
 * Add a "Content Type" value to the set of content types that can be negotiated
 * by the writer. This function makes a copy of the provided string. This
 * function may be called multiple times, in which case multiple "Content Type"
 * values will be accepted by the reader.
 *
 * For uni-directional streams like regular files, the negotiated content type
 * will simply be the first content type provided to this function. For
 * bi-directional streams like sockets, a handshake occurs and the remote end
 * determines which content type should be sent. In the latter case, after the
 * writer has been successfully opened with a call to fstrm_writer_open(), the
 * fstrm_writer_get_control() function should be called with `type` set to
 * `FSTRM_CONTROL_ACCEPT` and the control frame queried in order to determine
 * the negotiated content type.
 *
 * \param wopt
 *	`fstrm_writer_options` object.
 * \param content_type
 *	The "Content Type" string to copy. Note that this string is not
 *	NUL-terminated and may contain embedded NULs.
 * \param len_content_type
 *	The number of bytes in `content_type`.
 *
 * \retval #fstrm_res_success
 *	The "Content Type" field was successfully added.
 * \retval #fstrm_res_failure
 *	The "Content Type" string is too long.
 */
fstrm_res
fstrm_writer_options_add_content_type(
	struct fstrm_writer_options *wopt,
	const void *content_type,
	size_t len_content_type);

/**
 * Initialize a new `fstrm_writer` object based on an underlying `fstrm_rdwr`
 * object and an `fstrm_writer_options` object.
 *
 * The underlying `fstrm_rdwr` object MUST have a `write` method. It MAY
 * optionally have a `read` method, in which case the stream will be treated as
 * a bi-directional, handshaked stream. Otherwise, if there is no `read` method
 * the stream will be treated as a uni-directional stream.
 *
 * This function is useful for implementing functions that return new types of
 * `fstrm_writer` objects, such as fstrm_file_writer_init() and
 * fstrm_unix_writer_init().
 *
 * After a successful call to this function, the ownership of the `fstrm_rdwr`
 * object passes from the caller to the `fstrm_writer` object. The caller
 * should perform no further calls on the `fstrm_rdwr` object. The `fstrm_rdwr`
 * object will be cleaned up on a call to fstrm_writer_destroy().
 *
 * \param wopt
 *      `fstrm_writer_options` object. May be NULL, in which case default values
 *      will be used.
 *
 * \param rdwr
 *      Pointer to `fstrm_rdwr` object. Must be non-NULL. The `fstrm_rdwr`
 *      object must have a `write` method, and may optionally have a `read`
 *      method.
 *
 * \return
 *      `fstrm_writer` object.
 * \retval
 *      NULL on failure.
 */
struct fstrm_writer *
fstrm_writer_init(
	const struct fstrm_writer_options *wopt,
	struct fstrm_rdwr **rdwr);

/**
 * Destroy an `fstrm_writer` object. This implicitly calls fstrm_writer_close()
 * if necessary.
 *
 * \param w
 *	Pointer to `fstrm_writer` object.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_writer_destroy(struct fstrm_writer **w);

/**
 * Open an `fstrm_writer` object and prepare it to write data. For
 * bi-directional writer implementations, this performs content type
 * negotiation.
 *
 * This function may fail if there was an underlying problem opening the output
 * stream.
 *
 * \param w
 *	`fstrm_writer` object.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_writer_open(struct fstrm_writer *w);

/**
 * Close an `fstrm_writer` object. Open it has been closed, no data frames may
 * subsequently be written.
 *
 * Calling this function is optional; it may be implicitly invoked by a call to
 * fstrm_writer_destroy().
 *
 * \param w
 *	`fstrm_writer` object.
 *
 * \retval #fstrm_res_success
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_writer_close(struct fstrm_writer *w);

/**
 * Write a data frame to an `fstrm_writer` object.
 *
 * This function implicitly calls fstrm_writer_open() if necessary.
 *
 * \param w
 *	`fstrm_writer` object.
 * \param[in] data
 *	Buffer containing the data frame payload.
 * \param[in] len_data
 *	The number of bytes in `data`.
 *
 * \retval #fstrm_res_success
 *	The data frame was successfully written.
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_writer_write(
	struct fstrm_writer *w,
	const void *data,
	size_t len_data);

/**
 * Write multiple data frames to an `fstrm_writer` object.
 *
 * This function implicitly calls fstrm_writer_open() if necessary.
 * 
 * Data frames are passed similarly to the `writev()` system call, with an array
 * of `struct iovec` objects describing the data frame payloads and their
 * lengths. The complete set of data frames will be written to the output
 * stream after a successful call.
 *
 * \param w
 *	`fstrm_writer` object.
 * \param iov
 *	Array of `struct iovec` objects.
 * \param iovcnt
 *	Number of `struct iovec` objects in `iov`.
 *
 * \retval #fstrm_res_success
 *	The data frames were successfully written.
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_writer_writev(
	struct fstrm_writer *w,
	const struct iovec *iov,
	int iovcnt);

/**
 * Obtain a pointer to an `fstrm_control` object used during processing. Objects
 * returned by this function are owned by the `fstrm_reader` object and must not
 * be modified by the caller. After a call to fstrm_reader_destroy() these
 * pointers will no longer be valid.
 *
 * For example, with bi-directional streams this function can be used to obtain
 * a pointer to the ACCEPT control frame, which can be queried to see which
 * "Content Type" was negotiated during the opening of the writer.
 *
 * This function implicitly calls fstrm_writer_open() if necessary.
 *
 * \param w
 *      `fstrm_writer` object.
 * \param type
 *      Which control frame to return.
 * \param[out] control
 *      The `fstrm_control` object.
 *
 * \retval #fstrm_res_success
 *      If an `fstrm_control` object was returned.
 * \retval #fstrm_res_failure
 */
fstrm_res
fstrm_writer_get_control(
	struct fstrm_writer *w,
	fstrm_control_type type,
	struct fstrm_control **control);

/**@}*/

#endif /* FSTRM_WRITER_H */