toolchain/gcc/newlib/libc/stdio/fgetpos.c

   1 /*
   2 FUNCTION
   3 <<fgetpos>>---record position in a stream or file
   4
   5 INDEX
   6         fgetpos
   7 INDEX
   8         _fgetpos_r
   9
  10 ANSI_SYNOPSIS
  11         #include <stdio.h>
  12         int fgetpos(FILE *<[fp]>, fpos_t *<[pos]>);
  13         int _fgetpos_r(struct _reent *<[ptr]>, FILE *<[fp]>, fpos_t *<[pos]>);
  14
  15 TRAD_SYNOPSIS
  16         #include <stdio.h>
  17         int fgetpos(<[fp]>, <[pos]>)
  18         FILE *<[fp]>;
  19         fpos_t *<[pos]>;
  20
  21         int _fgetpos_r(<[ptr]>, <[fp]>, <[pos]>)
  22         struct _reent *<[ptr]>;
  23         FILE *<[fp]>;
  24         fpos_t *<[pos]>;
  25
  26 DESCRIPTION
  27 Objects of type <<FILE>> can have a ``position'' that records how much
  28 of the file your program has already read.  Many of the <<stdio>> functions
  29 depend on this position, and many change it as a side effect.
  30
  31 You can use <<fgetpos>> to report on the current position for a file
  32 identified by <[fp]>; <<fgetpos>> will write a value
  33 representing that position at <<*<[pos]>>>.  Later, you can
  34 use this value with <<fsetpos>> to return the file to this
  35 position.
  36
  37 In the current implementation, <<fgetpos>> simply uses a character
  38 count to represent the file position; this is the same number that
  39 would be returned by <<ftell>>.
  40
  41 RETURNS
  42 <<fgetpos>> returns <<0>> when successful.  If <<fgetpos>> fails, the
  43 result is <<1>>.  Failure occurs on streams that do not support
  44 positioning; the global <<errno>> indicates this condition with the
  45 value <<ESPIPE>>.
  46
  47 PORTABILITY
  48 <<fgetpos>> is required by the ANSI C standard, but the meaning of the
  49 value it records is not specified beyond requiring that it be
  50 acceptable as an argument to <<fsetpos>>.  In particular, other
  51 conforming C implementations may return a different result from
  52 <<ftell>> than what <<fgetpos>> writes at <<*<[pos]>>>.
  53
  54 No supporting OS subroutines are required.
  55 */
  56
  57 #include <stdio.h>
  58
  59 int
  60 _DEFUN (_fgetpos_r, (ptr, fp, pos),
  61         struct _reent * ptr _AND
  62         FILE * fp _AND
  63         _fpos_t * pos)
  64 {
  65   _flockfile(fp);
  66   *pos = _ftell_r (ptr, fp);
  67
  68   if (*pos != -1)
  69     {
  70       _funlockfile(fp);
  71       return 0;
  72     }
  73   _funlockfile(fp);
  74   return 1;
  75 }
  76
  77 #ifndef _REENT_ONLY
  78
  79 int
  80 _DEFUN (fgetpos, (fp, pos),
  81         FILE * fp _AND
  82         _fpos_t * pos)
  83 {
  84   return _fgetpos_r (_REENT, fp, pos);
  85 }
  86
  87 #endif /* !_REENT_ONLY */