summaryrefslogtreecommitdiff
path: root/doc/texinfo/stream.texi
blob: 706af4c36fca477db99b1e95256d853968899499 (plain)
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
@code{#include <mailutils/stream.h>}

These generic flags are interpreted as appropriate to the specific
streams.

@table @code
@item MU_STREAM_READ
@findex MU_STREAM_READ
The stream is open read only.
@item MU_STREAM_WRITE
@findex MU_STREAM_WRITE
The stream is open write only.
@item MU_STREAM_RDWR
@findex MU_STREAM_RDWR
The stream is open read and write.
@item MU_STREAM_APPEND
@findex MU_STREAM_APPEND
The stream is open in append mode for writing.
@item MU_STREAM_CREAT
@findex MU_STREAM_CREAT
The stream open will create the underlying resource (such as a file)
if it doesn't exist already.
@item MU_STREAM_NONBLOCK
@findex MU_STREAM_NONBLOCK
The stream is set non blocking.
@item MU_STREAM_NO_CHECK
@findex MU_STREAM_NO_CHECK
Stream is destroyed without checking for the owner.
@item MU_STREAM_NO_CLOSE
@findex MU_STREAM_NO_CLOSE
Stream doesn't close it's underlying resource when it is closed or destroyed.
@end table

@deftypefun int file_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags})
@end deftypefun

@deftypefun int tcp_stream_create (stream_t *@var{pstream}, const char *@var{host}, int @var{port}, int @var{flags})
@end deftypefun

@deftypefun int mapfile_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags})
@end deftypefun

@deftypefun int memory_stream_create (stream_t *@var{pstream}, const char *@var{filename}, int @var{flags})
@end deftypefun

@deftypefun int encoder_stream_create (stream_t *@var{pstream}, stream_t @var{iostream}, const char *@var{encoding})
@end deftypefun

@deftypefun int decoder_stream_create (stream_t *@var{pstream}, stream_t @var{iostream}, const char *@var{encoding})
@end deftypefun

@deftypefun void stream_destroy (stream_t *@var{pstream}, void *@var{owner})
@end deftypefun

@deftypefun int stream_open (stream_t @var{stream})
@end deftypefun

@deftypefun int stream_close (stream_t @var{stream})
@end deftypefun

@deftypefun int stream_is_seekable (stream_t @var{stream})
@end deftypefun

@deftypefun int stream_get_fd (stream_t @var{stream}, int *@var{pfd})
@end deftypefun

@deftypefun int stream_read (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten})
@end deftypefun

@deftypefun int stream_readline (stream_t @var{stream}, char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten})
@end deftypefun

@deftypefun int stream_size (stream_t @var{stream}, off_t *@var{psize})
@end deftypefun

@deftypefun int stream_truncate (stream_t @var{stream}, off_t @var{size})
@end deftypefun

@deftypefun int stream_write (stream_t @var{stream}, const char *@var{buffer}, size_t @var{buflen}, off_t @var{offset}, size_t *@var{pwriten})
@end deftypefun

@deftypefun int stream_setbufsiz (stream_t @var{stream}, size_t @var{size})
@end deftypefun

@deftypefun int stream_flush (stream_t @var{stream})
@end deftypefun

These functions will typically only be useful to implementors of streams.

@deftypefun int stream_create (stream_t *@var{pstream}, int @var{flags}, void *@var{owner})
Used to implement a new kind of stream.
@end deftypefun

@deftypefun int stream_get_flags (stream_t @var{stream}, int *@var{pflags})
@end deftypefun

@deftypefun int stream_get_state (stream_t @var{stream}, int *@var{pstate})
@table @code
@item MU_STREAM_STATE_OPEN
Last action was @code{stream_open}.
@item MU_STREAM_STATE_READ
Last action was @code{stream_read} or @code{stream_readline}.
@item MU_STREAM_STATE_WRITE
Last action was @code{stream_write}.
@item MU_STREAM_STATE_CLOSE
Last action was @code{stream_close}.
@end table
@end deftypefun

An example using @code{tcp_stream_create} to make a simple web client:

FIXME: this example won't build anymore.

@example
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <unistd.h>
#include <sys/select.h>

#include <mailutils/io.h>

const char *wbuf = "GET / HTTP/1.0\r\n\r\n";
char rbuf[1024];

int
main(int argc, char **argv)
@{
  int ret, off = 0, fd;
  stream_t stream;
  size_t nb;
  fd_set fds;

  argc = argc, argv = argv;

  ret = tcp_stream_create (&stream);
  if (ret != 0)
    @{
       fprintf (stderr, "tcp_stream_create: %s\n",
                mailutils_error(ret));
       exit (EXIT_FAILURE);
    @}

connect_again:
  ret = stream_open (stream, "www.netscape.com", 80,
                     MU_STREAM_NONBLOCK);
  if (ret != 0)
    @{
       if (ret == MU_ERROR_EAGAIN)
         @{
             ret = stream_get_fd(stream, &fd);
             if (ret != 0)
               @{
                   fprintf (stderr, "stream_get_fd: %s\n",
                            mailutils_error(ret));
                   exit (EXIT_FAILURE);
               @}
               FD_ZERO (&fds);
               FD_SET (fd, &fds);
               select (fd+1, NULL, &fds, NULL, NULL);
               goto connect_again;
          @}
          fprintf (stderr, "stream_open: %s\n", mailutils_error (ret));
          exit (EXIT_FAILURE);
    @}

    ret = stream_get_fd (stream, &fd);
    if (ret != 0)
      @{
         fprintf(stderr, "stream_get_fd: %s\n", strerror(ret));
         exit (EXIT_FAILURE);
      @}

write_again:
    ret = stream_write (stream, wbuf + off, strlen (wbuf), 0, &nb);
    if (ret != 0 )
      @{
         if (ret == EAGAIN)
           @{
              FD_ZERO (&fds);
              FD_SET (fd, &fds);
              select (fd + 1, NULL, &fds, NULL, NULL);
              off += nb;
              goto write_again;
           @}
         fprintf (stderr, "stream_write: %s\n", strerror(ret));
         exit (EXIT_FAILURE)
      @}

      if (nb != strlen (wbuf))
        @{
           fprintf(stderr, "stream_write: %s\n", "nb != wbuf length");
           exit (EXIT_FAILURE);
        @}

      do
        @{
read_again:
           ret = stream_read (stream, rbuf, sizeof (rbuf), 0, &nb);
           if (ret != 0)
             @{
                if (ret == EAGAIN)
                  @{
                     FD_ZERO (&fds);
                     FD_SET (fd, &fds);
                     select (fd + 1, &fds, NULL, NULL, NULL);
                     goto read_again;
                   @}
                 fprintf (stderr, "stream_read: %s\n", strerror(ret));
                 exit(EXIT_FAILURE);
              @}
              write (2, rbuf, nb);
         @} while (nb);

         ret = stream_close (stream);
         if (ret!= 0)
           @{
              fprintf (stderr, "stream_close: %s\n", strerror(ret));
              exit (EXIT_FAILURE);
           @}

         stream_destroy (&stream, NULL);
         exit (EXIT_SUCCESS);
@}
@end example

Return to:

Send suggestions and report system problems to the System administrator.