Tizen RT Libs&Environment  v1.1 D4
streams.h
Go to the documentation of this file.
1 /****************************************************************************
2  *
3  * Copyright 2016 Samsung Electronics All Rights Reserved.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing,
12  * software distributed under the License is distributed on an
13  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
14  * either express or implied. See the License for the specific
15  * language governing permissions and limitations under the License.
16  *
17  ****************************************************************************/
18 /****************************************************************************
19  *
20  * Copyright (C) 2009, 2011-2012, 2014 Gregory Nutt. All rights reserved.
21  * Author: Gregory Nutt <gnutt@nuttx.org>
22  *
23  * Redistribution and use in source and binary forms, with or without
24  * modification, are permitted provided that the following conditions
25  * are met:
26  *
27  * 1. Redistributions of source code must retain the above copyright
28  * notice, this list of conditions and the following disclaimer.
29  * 2. Redistributions in binary form must reproduce the above copyright
30  * notice, this list of conditions and the following disclaimer in
31  * the documentation and/or other materials provided with the
32  * distribution.
33  * 3. Neither the name NuttX nor the names of its contributors may be
34  * used to endorse or promote products derived from this software
35  * without specific prior written permission.
36  *
37  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
38  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
39  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
40  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
41  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
42  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
43  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
44  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
45  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
46  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
47  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
48  * POSSIBILITY OF SUCH DAMAGE.
49  *
50  ****************************************************************************/
57 #ifndef _INCLUDE_STREAMS_H
58 #define _INCLUDE_STREAMS_H
59 
60 /****************************************************************************
61  * Included Files
62  ****************************************************************************/
63 
64 #include <tinyara/config.h>
65 #include <stdio.h>
66 
67 /****************************************************************************
68  * Pre-processor Definitions
69  ****************************************************************************/
70 
71 /****************************************************************************
72  * Public Types
73  ****************************************************************************/
74 
75 /* These are the generic representations of a streams used by the TinyAra */
76 
77 struct lib_instream_s;
78 typedef int (*lib_getc_t)(FAR struct lib_instream_s *this);
79 
80 struct lib_outstream_s;
81 typedef void (*lib_putc_t)(FAR struct lib_outstream_s *this, int ch);
82 typedef int (*lib_flush_t)(FAR struct lib_outstream_s *this);
83 
89  lib_getc_t get; /* Get one character from the instream */
90  int nget; /* Total number of characters gotten. Written
91  * by get method, readable by user */
92 };
93 
99  lib_putc_t put; /* Put one character to the outstream */
100 #ifdef CONFIG_STDIO_LINEBUFFER
101  lib_flush_t flush; /* Flush any buffered characters in the outstream */
102 #endif
103  int nput; /* Total number of characters put. Written
104  * by put method, readable by user */
105 };
106 
107 /* Seek-able streams */
108 
109 struct lib_sistream_s;
110 typedef int (*lib_sigetc_t)(FAR struct lib_sistream_s *this);
111 typedef off_t (*lib_siseek_t)(FAR struct lib_sistream_s *this, off_t offset, int whence);
112 
113 struct lib_sostream_s;
114 typedef void (*lib_soputc_t)(FAR struct lib_sostream_s *this, int ch);
115 typedef int (*lib_soflush_t)(FAR struct lib_sostream_s *this);
116 typedef off_t (*lib_soseek_t)(FAR struct lib_sostream_s *this, off_t offset, int whence);
117 
123  lib_sigetc_t get; /* Get one character from the instream */
124  lib_siseek_t seek; /* Seek to a position in the instream */
125  int nget; /* Total number of characters gotten. Written
126  * by get method, readable by user */
127 };
128 
134  lib_soputc_t put; /* Put one character to the outstream */
135 #ifdef CONFIG_STDIO_LINEBUFFER
136  lib_soflush_t flush; /* Flush any buffered characters in the outstream */
137 #endif
138  lib_soseek_t seek; /* Seek a position in the output stream */
139  int nput; /* Total number of characters put. Written
140  * by put method, readable by user */
141 };
142 
143 /* These are streams that operate on a fixed-sized block of memory */
144 
151  FAR const char *buffer; /* Address of first byte in the buffer */
152  size_t buflen; /* Size of the buffer in bytes */
153 };
154 
161  FAR char *buffer; /* Address of first byte in the buffer */
162  size_t buflen; /* Size of the buffer in bytes */
163 };
164 
171  FAR const char *buffer; /* Address of first byte in the buffer */
172  size_t offset; /* Current buffer offset in bytes */
173  size_t buflen; /* Size of the buffer in bytes */
174 };
175 
182  FAR char *buffer; /* Address of first byte in the buffer */
183  size_t offset; /* Current buffer offset in bytes */
184  size_t buflen; /* Size of the buffer in bytes */
185 };
186 
187 /* These are streams that operate on a FILE */
188 
195  FAR FILE *stream;
196 };
197 
204  FAR FILE *stream;
205 };
206 
213  FAR FILE *stream;
214 };
215 
222  FAR FILE *stream;
223 };
224 
225 /* These are streams that operate on a file descriptor */
226 
233  int fd;
234 };
235 
242  int fd;
243 };
244 
251  int fd;
252 };
253 
260  int fd;
261 };
262 
263 /****************************************************************************
264  * Public Variables
265  ****************************************************************************/
266 
267 #undef EXTERN
268 #if defined(__cplusplus)
269 #define EXTERN extern "C"
270 extern "C" {
271 #else
272 #define EXTERN extern
273 #endif
274 
275 /****************************************************************************
276  * Public Function Prototypes
277  ****************************************************************************/
278 
279 /****************************************************************************
280  * Name: lib_meminstream, lib_memoutstream, lib_memsistream, lib_memsostream
281  *
282  * Description:
283  * Initializes a stream for use with a fixed-size memory buffer.
284  * Defined in lib/stdio/lib_meminstream.c and lib/stdio/lib_memoutstream.c.
285  * Seekable versions are defined in lib/stdio/lib_memsistream.c and
286  * lib/stdio/lib_memsostream.c.
287  *
288  * Input parameters:
289  * memstream - User allocated, uninitialized instance of struct
290  * lib_meminstream_s to be initialized.
291  * memstream - User allocated, uninitialized instance of struct
292  * lib_memoutstream_s to be initialized.
293  * bufstart - Address of the beginning of the fixed-size memory buffer
294  * buflen - Size of the fixed-sized memory buffer in bytes
295  *
296  * Returned Value:
297  * None (User allocated instance initialized).
298  *
299  ****************************************************************************/
300 
311 void lib_meminstream(FAR struct lib_meminstream_s *instream, FAR const char *bufstart, int buflen);
322 void lib_memoutstream(FAR struct lib_memoutstream_s *outstream, FAR char *bufstart, int buflen);
333 void lib_memsistream(FAR struct lib_memsistream_s *instream, FAR const char *bufstart, int buflen);
344 void lib_memsostream(FAR struct lib_memsostream_s *outstream, FAR char *bufstart, int buflen);
345 
346 /****************************************************************************
347  * Name: lib_stdinstream, lib_stdoutstream
348  *
349  * Description:
350  * Initializes a stream for use with a FILE instance.
351  * Defined in lib/stdio/lib_stdinstream.c and lib/stdio/lib_stdoutstream.c
352  *
353  * Input parameters:
354  * instream - User allocated, uninitialized instance of struct
355  * lib_stdinstream_s to be initialized.
356  * outstream - User allocated, uninitialized instance of struct
357  * lib_stdoutstream_s to be initialized.
358  * stream - User provided stream instance (must have been opened for
359  * the correct access).
360  *
361  * Returned Value:
362  * None (User allocated instance initialized).
363  *
364  ****************************************************************************/
365 
375 void lib_stdinstream(FAR struct lib_stdinstream_s *instream, FAR FILE *stream);
385 void lib_stdoutstream(FAR struct lib_stdoutstream_s *outstream, FAR FILE *stream);
395 void lib_stdsistream(FAR struct lib_stdsistream_s *instream, FAR FILE *stream);
405 void lib_stdsostream(FAR struct lib_stdsostream_s *outstream, FAR FILE *stream);
406 
407 /****************************************************************************
408  * Name: lib_rawinstream, lib_rawoutstream, lib_rawsistream, and
409  * lib_rawsostream,
410  *
411  * Description:
412  * Initializes a stream for use with a file descriptor.
413  * Defined in lib/stdio/lib_rawinstream.c and lib/stdio/lib_rawoutstream.c.
414  * Seekable versions are defined in lib/stdio/lib_rawsistream.c and
415  * lib/stdio/lib_rawsostream.c
416  *
417  * Input parameters:
418  * instream - User allocated, uninitialized instance of struct
419  * lib_rawinstream_s to be initialized.
420  * outstream - User allocated, uninitialized instance of struct
421  * lib_rawoutstream_s to be initialized.
422  * fd - User provided file/socket descriptor (must have been opened
423  * for the correct access).
424  *
425  * Returned Value:
426  * None (User allocated instance initialized).
427  *
428  ****************************************************************************/
438 void lib_rawinstream(FAR struct lib_rawinstream_s *instream, int fd);
448 void lib_rawoutstream(FAR struct lib_rawoutstream_s *outstream, int fd);
458 void lib_rawsistream(FAR struct lib_rawsistream_s *instream, int fd);
468 void lib_rawsostream(FAR struct lib_rawsostream_s *outstream, int fd);
469 
470 /****************************************************************************
471  * Name: lib_lowinstream, lib_lowoutstream
472  *
473  * Description:
474  * Initializes a stream for use with low-level, architecture-specific I/O.
475  * Defined in lib/stdio/lib_lowinstream.c and lib/stdio/lib_lowoutstream.c
476  *
477  * Input parameters:
478  * lowinstream - User allocated, uninitialized instance of struct
479  * lib_lowinstream_s to be initialized.
480  * lowoutstream - User allocated, uninitialized instance of struct
481  * lib_lowoutstream_s to be initialized.
482  *
483  * Returned Value:
484  * None (User allocated instance initialized).
485  *
486  ****************************************************************************/
487 
488 #ifdef CONFIG_ARCH_LOWGETC
489 
497 void lib_lowinstream(FAR struct lib_instream_s *lowinstream);
498 #endif
499 #ifdef CONFIG_ARCH_LOWPUTC
500 
508 void lib_lowoutstream(FAR struct lib_outstream_s *lowoutstream);
509 #endif
510 
511 /****************************************************************************
512  * Name: lib_zeroinstream, lib_nullinstream, lib_nulloutstream
513  *
514  * Description:
515  * Initializes NULL streams:
516  *
517  * o The stream created by lib_zeroinstream will return an infinitely long
518  * stream of zeroes. Defined in lib/stdio/lib_zeroinstream.c
519  * o The stream created by lib_nullinstream will return only EOF.
520  * Defined in lib/stdio/lib_nullinstream.c
521  * o The stream created by lib_nulloutstream will write all data to the
522  * bit-bucket. Defined in lib/stdio/lib_nulloutstream.c
523  *
524  * Input parameters:
525  * zeroinstream - User allocated, uninitialized instance of struct
526  * lib_instream_s to be initialized.
527  * nullinstream - User allocated, uninitialized instance of struct
528  * lib_instream_s to be initialized.
529  * nulloutstream - User allocated, uninitialized instance of struct
530  * lib_outstream_s to be initialized.
531  *
532  * Returned Value:
533  * None (User allocated instance initialized).
534  *
535  ****************************************************************************/
544 void lib_zeroinstream(FAR struct lib_instream_s *zeroinstream);
553 void lib_nullinstream(FAR struct lib_instream_s *nullinstream);
562 void lib_nulloutstream(FAR struct lib_outstream_s *nulloutstream);
563 
564 /****************************************************************************
565  * Name: lib_sylogstream
566  *
567  * Description:
568  * Initializes a stream for use with the configured syslog interface.
569  *
570  * Input parameters:
571  * lowoutstream - User allocated, uninitialized instance of struct
572  * lib_lowoutstream_s to be initialized.
573  *
574  * Returned Value:
575  * None (User allocated instance initialized).
576  *
577  ****************************************************************************/
578 
582 #ifdef CONFIG_SYSLOG
583 
586 void lib_syslogstream(FAR struct lib_outstream_s *stream);
587 #endif
588 
589 /****************************************************************************
590  * Name: lib_noflush
591  *
592  * Description:
593  * lib_noflush() provides a common, dummy flush method for output streams
594  * that are not flushable. Only used if CONFIG_STDIO_LINEBUFFER is selected.
595  *
596  * Return:
597  * Always returns OK
598  *
599  ****************************************************************************/
600 
601 #ifdef CONFIG_STDIO_LINEBUFFER
602 
605 int lib_noflush(FAR struct lib_outstream_s *stream);
606 #endif
607 
608 /****************************************************************************
609  * Name: lib_snoflush
610  *
611  * Description:
612  * lib_snoflush() provides a common, dummy flush method for seekable output
613  * streams that are not flushable. Only used if CONFIG_STDIO_LINEBUFFER
614  * is selected.
615  *
616  * Return:
617  * Always returns OK
618  *
619  ****************************************************************************/
620 
621 #ifdef CONFIG_STDIO_LINEBUFFER
622 
625 int lib_snoflush(FAR struct lib_sostream_s *this);
626 #endif
627 
628 /****************************************************************************
629  * Name: lib_sprintf and lib_vsprintf
630  *
631  * Description:
632  * Stream-oriented versions of sprintf and vsprintf.
633  *
634  ****************************************************************************/
638 int lib_sprintf(FAR struct lib_outstream_s *obj, FAR const char *fmt, ...);
642 int lib_vsprintf(FAR struct lib_outstream_s *obj, FAR const char *src, va_list ap);
646 #undef EXTERN
647 #if defined(__cplusplus)
648 }
649 #endif
650 
651 #endif /* _INCLUDE_STREAMS_H */
652 
Structure for getting character from the instream.
Definition: streams.h:88
FAR const char * buffer
Definition: streams.h:171
void lib_stdinstream(FAR struct lib_stdinstream_s *instream, FAR FILE *stream)
Initializes a stream for use with a FILE instance.
void lib_stdoutstream(FAR struct lib_stdoutstream_s *outstream, FAR FILE *stream)
Initializes a stream for use with a FILE instance.
void lib_memoutstream(FAR struct lib_memoutstream_s *outstream, FAR char *bufstart, int buflen)
Initializes a stream for use with a fixed-size memory buffer.
struct lib_instream_s public
Definition: streams.h:150
Structure for operation on a FILE with lib_sostream_s.
Definition: streams.h:220
Structure for operation on a fixed-sized block of memory with lib_instream_s.
Definition: streams.h:149
FAR FILE * stream
Definition: streams.h:204
struct lib_sistream_s public
Definition: streams.h:250
void lib_zeroinstream(FAR struct lib_instream_s *zeroinstream)
Initializes NULL stream.
off_t(* lib_siseek_t)(FAR struct lib_sistream_s *this, off_t offset, int whence)
Definition: streams.h:111
int(* lib_flush_t)(FAR struct lib_outstream_s *this)
Definition: streams.h:82
Structure for operation on a fd with lib_sistream_s.
Definition: streams.h:249
void lib_memsistream(FAR struct lib_memsistream_s *instream, FAR const char *bufstart, int buflen)
Initializes a stream for use with a fixed-size memory buffer.
void lib_nulloutstream(FAR struct lib_outstream_s *nulloutstream)
Initializes NULL stream.
struct lib_sostream_s public
Definition: streams.h:221
Structure for getting character from the instream with seek operation support.
Definition: streams.h:122
lib_siseek_t seek
Definition: streams.h:124
Structure for operation on a fixed-sized block of memory with lib_outstream_s.
Definition: streams.h:159
lib_putc_t put
Definition: streams.h:99
void(* lib_soputc_t)(FAR struct lib_sostream_s *this, int ch)
Definition: streams.h:114
struct lib_sostream_s public
Definition: streams.h:181
void lib_rawsistream(FAR struct lib_rawsistream_s *instream, int fd)
Initializes a stream for use with a file descriptor.
Structure for operation on a fd with lib_sostream_s.
Definition: streams.h:258
Structure for putting character to the outstream.
Definition: streams.h:98
FAR const char * buffer
Definition: streams.h:151
lib_soseek_t seek
Definition: streams.h:138
FAR FILE * stream
Definition: streams.h:222
Structure for putting character to the outstream with seek operation support.
Definition: streams.h:133
Structure for operation on a FILE with lib_outstream_s.
Definition: streams.h:202
FAR char * buffer
Definition: streams.h:161
int(* lib_getc_t)(FAR struct lib_instream_s *this)
Definition: streams.h:78
void lib_rawsostream(FAR struct lib_rawsostream_s *outstream, int fd)
Initializes a stream for use with a file descriptor.
off_t(* lib_soseek_t)(FAR struct lib_sostream_s *this, off_t offset, int whence)
Definition: streams.h:116
struct lib_outstream_s public
Definition: streams.h:203
int(* lib_soflush_t)(FAR struct lib_sostream_s *this)
Definition: streams.h:115
Structure for operation on a fd with lib_instream_s.
Definition: streams.h:231
struct file_struct FILE
Definition: stdio.h:183
void lib_lowoutstream(FAR struct lib_outstream_s *lowoutstream)
Initializes a stream for use with low-level, architecture-specific I/O.
void lib_meminstream(FAR struct lib_meminstream_s *instream, FAR const char *bufstart, int buflen)
Initializes a stream for use with a fixed-size memory buffer.
FAR FILE * stream
Definition: streams.h:213
Structure for operation on a FILE with lib_instream_s.
Definition: streams.h:193
Standard Input / Output APIs.
struct lib_instream_s public
Definition: streams.h:232
struct lib_outstream_s public
Definition: streams.h:160
void lib_stdsistream(FAR struct lib_stdsistream_s *instream, FAR FILE *stream)
Initializes a stream for use with a FILE instance.
struct lib_outstream_s public
Definition: streams.h:241
int(* lib_sigetc_t)(FAR struct lib_sistream_s *this)
Definition: streams.h:110
FAR char * buffer
Definition: streams.h:182
struct lib_instream_s public
Definition: streams.h:194
struct lib_sistream_s public
Definition: streams.h:170
void lib_rawinstream(FAR struct lib_rawinstream_s *instream, int fd)
Initializes a stream for use with a file descriptor.
struct lib_sistream_s public
Definition: streams.h:212
void(* lib_putc_t)(FAR struct lib_outstream_s *this, int ch)
Definition: streams.h:81
void lib_rawoutstream(FAR struct lib_rawoutstream_s *outstream, int fd)
Initializes a stream for use with a file descriptor.
void lib_nullinstream(FAR struct lib_instream_s *nullinstream)
Initializes NULL stream.
struct lib_sostream_s public
Definition: streams.h:259
void lib_stdsostream(FAR struct lib_stdsostream_s *outstream, FAR FILE *stream)
Initializes a stream for use with a FILE instance.
Structure for operation on a fixed-sized block of memory with lib_sostream_s.
Definition: streams.h:180
FAR FILE * stream
Definition: streams.h:195
Structure for operation on a fd with lib_outstream_s.
Definition: streams.h:240
Structure for operation on a FILE with lib_sistream_s.
Definition: streams.h:211
void lib_memsostream(FAR struct lib_memsostream_s *outstream, FAR char *bufstart, int buflen)
Initializes a stream for use with a fixed-size memory buffer.
lib_soputc_t put
Definition: streams.h:134
Structure for operation on a fixed-sized block of memory with lib_sistream_s.
Definition: streams.h:169