man/man3/fopen.3

   1 .\" Copyright (c) 1980 Regents of the University of California.
   2 .\" All rights reserved.  The Berkeley software License Agreement
   3 .\" specifies the terms and conditions for redistribution.
   4 .\"
   5 .\"     @(#)fopen.3s    6.3 (Berkeley) 5/27/86
   6 .\"
   7 .TH FOPEN 3  "May 27, 1986"
   8 .UC 4
   9 .SH NAME
  10 fopen, freopen, fdopen \- open a stream
  11 .SH SYNOPSIS
  12 .nf
  13 .ft B
  14 #include <stdio.h>
  15
  16 FILE *fopen(const char *\fIfilename\fP, const char *\fItype\fP)
  17 FILE *freopen(const char *\fIfilename\fP, const char *\fItype\fP, FILE *\fIstream\fP)
  18 FILE *fdopen(int \fIfildes\fP, const char *\fItype\fP)
  19 .ft R
  20 .fi
  21 .SH DESCRIPTION
  22 .B Fopen
  23 opens the file named by
  24 .I filename
  25 and associates a stream with it.
  26 .B Fopen
  27 returns a pointer to be used to identify the stream in subsequent operations.
  28 .PP
  29 .I Type
  30 is a character string having one of the following values:
  31 .TP 5
  32 "r"
  33 open for reading
  34 .ns
  35 .TP 5
  36 "w"
  37 create for writing
  38 .ns
  39 .TP 5
  40 "a"
  41 append: open for writing at end of file, or create for writing
  42 .PP
  43 In addition, each
  44 .I type
  45 may be followed by a "+" to have the file opened for reading and writing.
  46 "r+" positions the stream at the beginning of the file, "w+" creates
  47 or truncates it, and "a+" positions it at the end.  Both reads and writes
  48 may be used on read/write streams, with the limitation that an
  49 .BR fseek ,
  50 .BR rewind ,
  51 or reading an end-of-file must be used between a read and a write or vice-versa.
  52 .PP
  53 .B Freopen
  54 substitutes the named file in place of the open
  55 .IR stream .
  56 It returns the original value of
  57 .IR stream .
  58 The original stream is closed.
  59 .PP
  60 .B Freopen
  61 is typically used to attach the preopened constant names,
  62 .B stdin, stdout, stderr,
  63 to specified files.
  64 .PP
  65 .B Fdopen
  66 associates a stream with a file descriptor obtained from
  67 .BR open ,
  68 .BR dup ,
  69 .BR creat ,
  70 or
  71 .BR pipe (2).
  72 The
  73 .I type
  74 of the stream must agree with the mode of the open file.
  75 .SH "SEE ALSO"
  76 .BR open (2),
  77 .BR fclose (3).
  78 .SH DIAGNOSTICS
  79 .B Fopen
  80 and
  81 .B freopen
  82 return the pointer
  83 .SM
  84 .B NULL
  85 if
  86 .I filename
  87 cannot be accessed,
  88 if too many files are already open,
  89 or if other resources needed cannot be allocated.
  90 .SH BUGS
  91 .B Fdopen
  92 is not portable to systems other than UNIX.
  93 .PP
  94 The read/write
  95 .I types
  96 do not exist on all systems.  Those systems without
  97 read/write modes will probably treat the
  98 .I type
  99 as if the "+" was not present.  These are unreliable in any event.