pd.if.org Git - pdclib.old/blob - man3/unlocked_stdio.3

   1 .\" This file is part of the Public Domain C Library " "PDCLib).
   2 .\" Permission is granted to use" "modify" "and / or redistribute at will.
   3 .\"
   4 .Dd
   5 .Dt UNLOCKED_STDIO 3
   6 .Os
   7 .\"
   8 .Sh NAME
   9 .Nm *_unlocked
  10 .Nd unlocked stdio routnes
  11 .\"
  12 .Sh SYNOPSIS
  13 .Sy #define _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600 || _SVID_SOURCE || _BSD_SOURCE
  14 .In stdio.h
  15 .Fn "int getc_unlocked" "FILE *stream"
  16 .Fn "int getchar_unlocked" "void"
  17 .Fn "int putc_unlocked" "int c" "FILE *stream"
  18 .Fn "int putchar_unlocked" "int c"
  19 .Pp
  20 .Sy #define _SVID_SOURCE || _BSD_SOURCE
  21 .In stdio.h
  22 .Fn "void clearerr_unlocked" "FILE *stream"
  23 .Fn "int feof_unlocked" "FILE *stream"
  24 .Fn "int ferror_unlocked" "FILE *stream"
  25 .Fn "int fileno_unlocked" "FILE *stream"
  26 .Fn "int fflush_unlocked" "FILE *stream"
  27 .Fn "int fgetc_unlocked" "FILE *stream"
  28 .Fn "int fputc_unlocked" "int c" "FILE *stream"
  29 .Fn "size_t fread_unlocked" "void *ptr" "size_t size" "size_t n" "FILE *stream"
  30 .Fn "size_t fwrite_unlocked" "const void *ptr" "size_t size" "size_t n" "FILE *stream"
  31 .Pp
  32 .Sy #define _GNU_SOURCE
  33 .In stdio.h
  34 .Fn "char *fgets_unlocked" "char *s" "int n" "FILE *stream"
  35 .Fn "int fputs_unlocked" "const char *s" "FILE *stream"
  36 .Pp
  37 .Sy #define _PDCLIB_EXTENSIONS
  38 .In stdio.h
  39 .Fn "int fgetpos_unlocked" "FILE * restrict stream" "fpos_t * restrict pos"
  40 .Fn "int fsetpos_unlocked" "FILE * stream" "const fpos_t * pos"
  41 .Fn "long int ftell_unlocked" "FILE * stream"
  42 .Fn "int fseek_unlocked" "FILE * stream" "long int offset" "int whence"
  43 .Fn "void rewind_unlocked" "FILE * stream"
  44 .Fn "int puts_unlocked" "const char * s"
  45 .Fn "int ungetc_unlocked" "int c" "FILE * stream"
  46 .Fn "int printf_unlocked" "const char * restrict format" "..."
  47 .Fn "int vprintf_unlocked" "const char * restrict format" "va_list arg"
  48 .Fn "int fprintf_unlocked" "FILE * restrict stream" "const char * restrict format" "..."
  49 .Fn "int vfprintf_unlocked" "FILE * restrict stream" "const char * restrict format" "va_list arg"
  50 .Fn "int scanf_unlocked" "const char * restrict format" "..."
  51 .Fn "int vscanf_unlocked" "const char * restrict format" "va_list arg"
  52 .Fn "int fscanf_unlocked" "FILE * restrict stream" "const char * restrict format" "..."
  53 .Fn "int vfscanf_unlocked" "FILE * restrict stream" "const char * restrict format" "va_list arg"
  54 .\"
  55 .Sh DESCRIPTION
  56 Functions with analogous purposes to the same functions named without the
  57 .Li _unlocked
  58 prefix, excepting that they must be called with the stream already locked (they
  59 do not lock the stream themself)
  60 .Pp
  61 Befor calling these functions, callers must lock the stream upon which they wish
  62 to operate on with the
  63 .Fn flockfile
  64 or
  65 .Fn ftrylockfile
  66 function. Once they are done operating on the stream, they should unlock the
  67 stream using the
  68 .Fn funlockfile
  69 to allow other threads to use the stream
  70 .Pp
  71 It is undefined behaviour to operate on a stream using one of these functions
  72 without previously locking the stream appropriately, even in a single threaded
  73 application.
  74 .\"
  75 .Sh IMPLEMENTATION NOTES
  76 PDCLib implements the locked variants of most functions using the following
  77 template:
  78 .Bd -literal -offset indent -compact
  79 type function(FILE* file, other arguments...)
  80 {
  81     flockfile(file);
  82     type rv = function_unlocked(file, other arguments...)
  83     funlockfile(file);
  84     return rv;
  85 }
  86 .Ed
  87 .\"
  88 .Sh SEE ALSO
  89 .Xr fopen 3
  90 .Xr fclose 3
  91 .Xr flockfile 3
  92 .Xr mtx_t 3
  93 .\"
  94 .Sh STANDARDS
  95 The most basic I/O routines (getc/getchar/putc/putchar_unlocked) are from
  96 .St -p1003.1-2001 .
  97 A more complete set of routines comes from
  98 .St -svid4
  99 and
 100 .Bx .
 101 .Fn fgets_unlocked
 102 and
 103 .Fn fputs_unlocked
 104 are extensions originating from glibc. Finally, PDCLib extends the set to
 105 encompass the entirety of the C standard I/o library.