freopen(3c) - osol9

1freopen(3C)              Standard C Library Functions              freopen(3C)
2
3
4

NAME

6       freopen - open a stream
7

SYNOPSIS

9       #include <stdio.h>
10
11       FILE *freopen(const char *filename, const char *mode, FILE *stream);
12
13

DESCRIPTION

15       The freopen() function first attempts to flush the stream and close any
16       file descriptor associated with stream. Failure to flush or  close  the
17       file  successfully is ignored. The error and end-of-file indicators for
18       the stream are cleared.
19
20
21       The freopen() function opens the file  whose  pathname  is  the  string
22       pointed  to  by filename and associates the stream pointed to by stream
23       with it. The mode argument is used just as in fopen(3C).
24
25
26       If filename is a null pointer and the  application  comforms  to  SUSv3
27       (see  standards(5)), the freopen() function attempts to change the mode
28       of the stream to that specified by mode, as though the name of the file
29       currently  associated  with  the  stream  had been used.  The following
30       changes of mode are permitted, depending upon the access  mode  of  the
31       file descriptor underlying the stream:
32
33           o      When  +  is  specified,  the  file  descriptor  mode must be
34                  O_RDWR.
35
36           o      When r is  specified,  the  file  descriptor  mode  must  be
37                  O_RDONLY or O_RDWR.
38
39           o      When  a  or w is specified, the file descriptor mode must be
40                  O_WRONLY or O_RDWR.
41
42
43       If the filename is a null pointer and the application does not  comform
44       to SUSv3, freopen() returns a null pointer.
45
46
47       The original stream is closed regardless of whether the subsequent open
48       succeeds.
49
50
51       After a successful call to the freopen() function, the  orientation  of
52       the stream is cleared, the encoding rule is cleared, and the associated
53       mbstate_t object is set to describe an initial conversion state.
54
55
56       The largest value that can be represented correctly  in  an  object  of
57       type  off_t  will be established as the offset maximum in the open file
58       description.
59

RETURN VALUES

61       Upon successful completion, freopen() returns the value of stream. Oth‐
62       erwise,  a  null  pointer  is returned and errno is set to indicate the
63       error.
64

ERRORS

66       The freopen() function will fail if:
67
68       EACCES          Search permission is denied on a component of the  path
69                       prefix,  or  the file exists and the permissions speci‐
70                       fied by mode are denied, or the file does not exist and
71                       write  permission is denied for the parent directory of
72                       the file to be created.
73
74
75       EBADF           The application comforms to SUSv3, the  filename  argu‐
76                       ment  is a null pointer, and either the underlying file
77                       descriptor is not valid or the mode specified when  the
78                       underlying  file descriptor was opened does not support
79                       the file access modes requested by the mode argument.
80
81
82       EFAULT          The application does not comform to SUSv3 and the file‐
83                       name argument is a null pointer.
84
85
86       EINTR           A signal was caught during freopen().
87
88
89       EISDIR          The  named  file is a directory and mode requires write
90                       access.
91
92
93       ELOOP           Too many symbolic links were encountered  in  resolving
94                       path.
95
96
97       EMFILE          There are {OPEN_MAX} file descriptors currently open in
98                       the calling process.
99
100
101       ENAMETOOLONG    The length of the  filename  exceeds  {PATH_MAX}  or  a
102                       pathname component is longer than {NAME_MAX}.
103
104
105       ENFILE          The maximum allowable number of files is currently open
106                       in the system.
107
108
109       ENOENT          A component of filename does not name an existing  file
110                       or filename is an empty string.
111
112
113       ENOSPC          The directory or file system that would contain the new
114                       file cannot be expanded, the file does not  exist,  and
115                       it was to be created.
116
117
118       ENOTDIR         A component of the path prefix is not a directory.
119
120
121       ENXIO           The  named file is a character special or block special
122                       file, and the device associated with this special  file
123                       does not exist.
124
125
126       EOVERFLOW       The current value of the file position cannot be repre‐
127                       sented correctly in an object of type off_t.
128
129
130       EROFS           The named file resides on a read-only file  system  and
131                       mode requires write access.
132
133
134
135       The freopen() function may fail if:
136
137       EINVAL          The value of the mode argument is not valid.
138
139
140       ENAMETOOLONG    Pathname  resolution  of  a  symbolic  link produced an
141                       intermediate result whose length exceeds {PATH_MAX}.
142
143
144       ENOMEM          Insufficient storage space is available.
145
146
147       ENXIO           A request was made of a  non-existent  device,  or  the
148                       request was outside the capabilities of the device.
149
150
151       ETXTBSY         The file is a pure procedure (shared text) file that is
152                       being executed and mode requires write access.
153
154

USAGE

156       The freopen() function  is  typically  used  to  attach  the  preopened
157       streams  associated  with  stdin,  stdout and stderr to other files. By
158       default stderr is unbuffered, but the use of freopen() will cause it to
159       become buffered or line-buffered.
160
161
162       The  freopen()  function  has  a transitional interface for 64-bit file
163       offsets.  See lf64(5).
164

ATTRIBUTES

166       See attributes(5) for descriptions of the following attributes:
167
168
169
170
171       ┌─────────────────────────────┬─────────────────────────────┐
172       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
173       ├─────────────────────────────┼─────────────────────────────┤
174       │Interface Stability          │Standard                     │
175       ├─────────────────────────────┼─────────────────────────────┤
176       │MT-Level                     │MT-Safe                      │
177       └─────────────────────────────┴─────────────────────────────┘
178