man3/fopencookie.3

   1 .\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
   2 .\"      <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH FOPENCOOKIE 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 fopencookie \- opening a custom stream
  29 .SH SYNOPSIS
  30 .nf
  31 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  32 .B #include <stdio.h>
  33 .PP
  34 .BI "FILE *fopencookie(void *restrict " cookie ", const char *restrict " mode ,
  35 .BI "                  cookie_io_functions_t " io_funcs );
  36 .fi
  37 .SH DESCRIPTION
  38 The
  39 .BR fopencookie ()
  40 function allows the programmer to create a custom implementation
  41 for a standard I/O stream.
  42 This implementation can store the stream's data at a location of
  43 its own choosing; for example,
  44 .BR fopencookie ()
  45 is used to implement
  46 .BR fmemopen (3),
  47 which provides a stream interface to data that is stored in a
  48 buffer in memory.
  49 .PP
  50 In order to create a custom stream the programmer must:
  51 .IP * 3
  52 Implement four "hook" functions that are used internally by the
  53 standard I/O library when performing I/O on the stream.
  54 .IP *
  55 Define a "cookie" data type,
  56 a structure that provides bookkeeping information
  57 (e.g., where to store data) used by the aforementioned hook functions.
  58 The standard I/O package knows nothing about the contents of this cookie
  59 (thus it is typed as
  60 .IR "void\ *"
  61 when passed to
  62 .BR fopencookie ()),
  63 but automatically supplies the cookie
  64 as the first argument when calling the hook functions.
  65 .IP *
  66 Call
  67 .BR fopencookie ()
  68 to open a new stream and associate the cookie and hook functions
  69 with that stream.
  70 .PP
  71 The
  72 .BR fopencookie ()
  73 function serves a purpose similar to
  74 .BR fopen (3):
  75 it opens a new stream and returns a pointer to a
  76 .I FILE
  77 object that is used to operate on that stream.
  78 .PP
  79 The
  80 .I cookie
  81 argument is a pointer to the caller's cookie structure
  82 that is to be associated with the new stream.
  83 This pointer is supplied as the first argument when the standard I/O
  84 library invokes any of the hook functions described below.
  85 .PP
  86 The
  87 .I mode
  88 argument serves the same purpose as for
  89 .BR fopen (3).
  90 The following modes are supported:
  91 .IR r ,
  92 .IR w ,
  93 .IR a ,
  94 .IR r+ ,
  95 .IR w+ ,
  96 and
  97 .IR a+ .
  98 See
  99 .BR fopen (3)
 100 for details.
 101 .PP
 102 The
 103 .I io_funcs
 104 argument is a structure that contains four fields pointing to the
 105 programmer-defined hook functions that are used to implement this stream.
 106 The structure is defined as follows
 107 .PP
 108 .in +4n
 109 .EX
 110 typedef struct {
 111     cookie_read_function_t  *read;
 112     cookie_write_function_t *write;
 113     cookie_seek_function_t  *seek;
 114     cookie_close_function_t *close;
 115 } cookie_io_functions_t;
 116 .EE
 117 .in
 118 .PP
 119 The four fields are as follows:
 120 .TP
 121 .I cookie_read_function_t *read
 122 This function implements read operations for the stream.
 123 When called, it receives three arguments:
 124 .IP
 125     ssize_t read(void *cookie, char *buf, size_t size);
 126 .IP
 127 The
 128 .I buf
 129 and
 130 .I size
 131 arguments are, respectively,
 132 a buffer into which input data can be placed and the size of that buffer.
 133 As its function result, the
 134 .I read
 135 function should return the number of bytes copied into
 136 .IR buf ,
 137 0 on end of file, or \-1 on error.
 138 The
 139 .I read
 140 function should update the stream offset appropriately.
 141 .IP
 142 If
 143 .I *read
 144 is a null pointer,
 145 then reads from the custom stream always return end of file.
 146 .TP
 147 .I cookie_write_function_t *write
 148 This function implements write operations for the stream.
 149 When called, it receives three arguments:
 150 .IP
 151     ssize_t write(void *cookie, const char *buf, size_t size);
 152 .IP
 153 The
 154 .I buf
 155 and
 156 .I size
 157 arguments are, respectively,
 158 a buffer of data to be output to the stream and the size of that buffer.
 159 As its function result, the
 160 .I write
 161 function should return the number of bytes copied from
 162 .IR buf ,
 163 or 0 on error.
 164 (The function must not return a negative value.)
 165 The
 166 .I write
 167 function should update the stream offset appropriately.
 168 .IP
 169 If
 170 .I *write
 171 is a null pointer,
 172 then output to the stream is discarded.
 173 .TP
 174 .I cookie_seek_function_t *seek
 175 This function implements seek operations on the stream.
 176 When called, it receives three arguments:
 177 .IP
 178     int seek(void *cookie, off64_t *offset, int whence);
 179 .IP
 180 The
 181 .I *offset
 182 argument specifies the new file offset depending on which
 183 of the following three values is supplied in
 184 .IR whence :
 185 .RS
 186 .TP
 187 .B SEEK_SET
 188 The stream offset should be set
 189 .I *offset
 190 bytes from the start of the stream.
 191 .TP
 192 .B SEEK_CUR
 193 .I *offset
 194 should be added to the current stream offset.
 195 .TP
 196 .B SEEK_END
 197 The stream offset should be set to the size of the stream plus
 198 .IR *offset .
 199 .RE
 200 .IP
 201 Before returning, the
 202 .I seek
 203 function should update
 204 .I *offset
 205 to indicate the new stream offset.
 206 .IP
 207 As its function result, the
 208 .I seek
 209 function should return 0 on success, and \-1 on error.
 210 .IP
 211 If
 212 .I *seek
 213 is a null pointer,
 214 then it is not possible to perform seek operations on the stream.
 215 .TP
 216 .I cookie_close_function_t *close
 217 This function closes the stream.
 218 The hook function can do things such as freeing buffers allocated
 219 for the stream.
 220 When called, it receives one argument:
 221 .IP
 222     int close(void *cookie);
 223 .IP
 224 The
 225 .I cookie
 226 argument is the cookie that the programmer supplied when calling
 227 .BR fopencookie ().
 228 .IP
 229 As its function result, the
 230 .I close
 231 function should return 0 on success, and
 232 .B EOF
 233 on error.
 234 .IP
 235 If
 236 .I *close
 237 is NULL, then no special action is performed when the stream is closed.
 238 .SH RETURN VALUE
 239 On success
 240 .BR fopencookie ()
 241 returns a pointer to the new stream.
 242 On error, NULL is returned.
 243 .\" .SH ERRORS
 244 .\" It's not clear if errno ever gets set...
 245 .SH ATTRIBUTES
 246 For an explanation of the terms used in this section, see
 247 .BR attributes (7).
 248 .ad l
 249 .nh
 250 .TS
 251 allbox;
 252 lbx lb lb
 253 l l l.
 254 Interface       Attribute       Value
 255 T{
 256 .BR fopencookie ()
 257 T}      Thread safety   MT-Safe
 258 .TE
 259 .hy
 260 .ad
 261 .sp 1
 262 .SH CONFORMING TO
 263 This function is a nonstandard GNU extension.
 264 .SH EXAMPLES
 265 The program below implements a custom stream whose functionality
 266 is similar (but not identical) to that available via
 267 .BR fmemopen (3).
 268 It implements a stream whose data is stored in a memory buffer.
 269 The program writes its command-line arguments to the stream,
 270 and then seeks through the stream reading two out of every
 271 five characters and writing them to standard output.
 272 The following shell session demonstrates the use of the program:
 273 .PP
 274 .in +4n
 275 .EX
 276 .RB "$" " ./a.out \(aqhello world\(aq"
 277 /he/
 278 / w/
 279 /d/
 280 Reached end of file
 281 .EE
 282 .in
 283 .PP
 284 Note that a more general version of the program below
 285 could be improved to more robustly handle various error situations
 286 (e.g., opening a stream with a cookie that already has an open stream;
 287 closing a stream that has already been closed).
 288 .SS Program source
 289 \&
 290 .EX
 291 #define _GNU_SOURCE
 292 #include <sys/types.h>
 293 #include <stdio.h>
 294 #include <stdlib.h>
 295 #include <unistd.h>
 296 #include <string.h>
 297
 298 #define INIT_BUF_SIZE 4
 299
 300 struct memfile_cookie {
 301     char   *buf;        /* Dynamically sized buffer for data */
 302     size_t  allocated;  /* Size of buf */
 303     size_t  endpos;     /* Number of characters in buf */
 304     off_t   offset;     /* Current file offset in buf */
 305 };
 306
 307 ssize_t
 308 memfile_write(void *c, const char *buf, size_t size)
 309 {
 310     char *new_buff;
 311     struct memfile_cookie *cookie = c;
 312
 313     /* Buffer too small? Keep doubling size until big enough. */
 314
 315     while (size + cookie\->offset > cookie\->allocated) {
 316         new_buff = realloc(cookie\->buf, cookie\->allocated * 2);
 317         if (new_buff == NULL) {
 318             return \-1;
 319         } else {
 320             cookie\->allocated *= 2;
 321             cookie\->buf = new_buff;
 322         }
 323     }
 324
 325     memcpy(cookie\->buf + cookie\->offset, buf, size);
 326
 327     cookie\->offset += size;
 328     if (cookie\->offset > cookie\->endpos)
 329         cookie\->endpos = cookie\->offset;
 330
 331     return size;
 332 }
 333
 334 ssize_t
 335 memfile_read(void *c, char *buf, size_t size)
 336 {
 337     ssize_t xbytes;
 338     struct memfile_cookie *cookie = c;
 339
 340     /* Fetch minimum of bytes requested and bytes available. */
 341
 342     xbytes = size;
 343     if (cookie\->offset + size > cookie\->endpos)
 344         xbytes = cookie\->endpos \- cookie\->offset;
 345     if (xbytes < 0)     /* offset may be past endpos */
 346        xbytes = 0;
 347
 348     memcpy(buf, cookie\->buf + cookie\->offset, xbytes);
 349
 350     cookie\->offset += xbytes;
 351     return xbytes;
 352 }
 353
 354 int
 355 memfile_seek(void *c, off64_t *offset, int whence)
 356 {
 357     off64_t new_offset;
 358     struct memfile_cookie *cookie = c;
 359
 360     if (whence == SEEK_SET)
 361         new_offset = *offset;
 362     else if (whence == SEEK_END)
 363         new_offset = cookie\->endpos + *offset;
 364     else if (whence == SEEK_CUR)
 365         new_offset = cookie\->offset + *offset;
 366     else
 367         return \-1;
 368
 369     if (new_offset < 0)
 370         return \-1;
 371
 372     cookie\->offset = new_offset;
 373     *offset = new_offset;
 374     return 0;
 375 }
 376
 377 int
 378 memfile_close(void *c)
 379 {
 380     struct memfile_cookie *cookie = c;
 381
 382     free(cookie\->buf);
 383     cookie\->allocated = 0;
 384     cookie\->buf = NULL;
 385
 386     return 0;
 387 }
 388
 389 int
 390 main(int argc, char *argv[])
 391 {
 392     cookie_io_functions_t  memfile_func = {
 393         .read  = memfile_read,
 394         .write = memfile_write,
 395         .seek  = memfile_seek,
 396         .close = memfile_close
 397     };
 398     FILE *stream;
 399     struct memfile_cookie mycookie;
 400     size_t nread;
 401     char buf[1000];
 402
 403     /* Set up the cookie before calling fopencookie(). */
 404
 405     mycookie.buf = malloc(INIT_BUF_SIZE);
 406     if (mycookie.buf == NULL) {
 407         perror("malloc");
 408         exit(EXIT_FAILURE);
 409     }
 410
 411     mycookie.allocated = INIT_BUF_SIZE;
 412     mycookie.offset = 0;
 413     mycookie.endpos = 0;
 414
 415     stream = fopencookie(&mycookie, "w+", memfile_func);
 416     if (stream == NULL) {
 417         perror("fopencookie");
 418         exit(EXIT_FAILURE);
 419     }
 420
 421     /* Write command\-line arguments to our file. */
 422
 423     for (int j = 1; j < argc; j++)
 424         if (fputs(argv[j], stream) == EOF) {
 425             perror("fputs");
 426             exit(EXIT_FAILURE);
 427         }
 428
 429     /* Read two bytes out of every five, until EOF. */
 430
 431     for (long p = 0; ; p += 5) {
 432         if (fseek(stream, p, SEEK_SET) == \-1) {
 433             perror("fseek");
 434             exit(EXIT_FAILURE);
 435         }
 436         nread = fread(buf, 1, 2, stream);
 437         if (nread == 0) {
 438             if (ferror(stream) != 0) {
 439                 fprintf(stderr, "fread failed\en");
 440                 exit(EXIT_FAILURE);
 441             }
 442             printf("Reached end of file\en");
 443             break;
 444         }
 445
 446         printf("/%.*s/\en", (int) nread, buf);
 447     }
 448
 449     exit(EXIT_SUCCESS);
 450 }
 451 .EE
 452 .SH SEE ALSO
 453 .BR fclose (3),
 454 .BR fmemopen (3),
 455 .BR fopen (3),
 456 .BR fseek (3)