/usr/share/gtk-doc/html/gmime-3.2/gmime-streams.html is in libgmime-3.0-doc 3.2.0-1.
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 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Streams: GMime 3.0 Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GMime 3.0 Reference Manual">
<link rel="up" href="fundamentals.html" title="Part II. GMime Fundamentals">
<link rel="prev" href="fundamentals.html" title="Part II. GMime Fundamentals">
<link rel="next" href="gmime-filters.html" title="Stream Filters">
<meta name="generator" content="GTK-Doc V1.25 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="fundamentals.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="fundamentals.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="gmime-filters.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="gmime-streams"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">Streams</span></h2>
<p>Streams — How to use Streams</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="stream-overview"></a><h2>Overview of Streams</h2>
<p>Streams are the fundamental method for reading and writing
data used by GMime. You'll probably notice that the basic API is
similar to that of the low-level Unix I/O layer (read(), write(),
lseek(), etc) with some additional niceties such as a printf-like
function.</p>
<p>The three (3) basic stream types are: GMimeStreamFile,
GMimeStreamFs and GMimeStreamMem. You can manipulate all three
streams using the GMimeStream interfaces. In addition, some of
these streams have extended interfaces to allow more fine grained
manipulation.</p>
<p>GMimeStreamFile and GMimeStreamFs are very similar in that
they are both meant for reading and writing data to the file
system (in the form of files). Since GMimeStreamFile is an
abstracted layer above the standard libc FILE type, one of the
added benefits is buffered I/O. GMimeStreamFs, on the other hand,
is an abstracted layer above Unix file descriptors. While a
GMimeStreamFs can be used on top of a UNIX socket or pipe, you
must be careful because sockets and pipes are not seekable
(see GMimeStreamPipe for a solution to this).</p>
<p>Unlike the previous 2 stream types, GMimeStreamMem does not
interact with the file system at all (except maybe the swap
partition/file indirectly). Memory streams are handy when you want
reads and writes to be nearly instantaneous and/or if you don't
want to create a temporary file on disk.</p>
<p>The five (5) advanced stream types are GMimeStreamMmap,
GMimeStreamNull, GMimeStreamPipe, GMimeStreamBuffer and
GMimeStreamFilter.</p>
<p>Our most simple stream, GMimeStreamNull, is the stream
equivalent of /dev/null on Unix systems. The main difference is
that GMimeStreamNull records the number of bytes written to it -
you may find this useful if you need to know the number of bytes a
GMimeObject (for example) will require.</p>
<p>GMimeStreamMmap is a memory-mapped stream. This isn't
guaranteed to work on all systems since not all systems support
the POSIX mmap system call, but for those that do - this might
present a faster stream than GMimeStreamFs and/or
GMimeStreamFile. You'll have to do some experimentation to know
for sure.</p>
<p>GMimeStreamPipe is just like GMimeStreamFs except that it
doesn't support seeking, thus being perfect for use with sockets
and pipes.</p>
<p>The GMimeStreamBuffer can be used on top of any other type
of stream and has 3 modes: block reads, block writes, and cached
reads. Block reads are especially useful if you will be making a
lot of small reads from a stream that accesses the file
system. Block writes are useful for very much the same reason. The
final mode, cached reads, can become memory intensive but can be
very helpful when inheriting from a stream that does not support
seeking (Note: this mode is the least tested so be careful using
it).</p>
<p>Our final stream type, GMimeStreamFilter, can also be used
on top of another stream. This stream, as you may have guessed,
filters reads and writes to its inherited stream. For example, one
could write a compression filter and apply it to a
GMimeStreamFilter and any further reads or writes would be
(un)compressed.</p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.25</div>
</body>
</html>
|