1In_channel(3)                    OCaml library                   In_channel(3)
2
3
4

NAME

6       In_channel - Input channels.
7

Module

9       Module   In_channel
10

Documentation

12       Module In_channel
13        : sig end
14
15
16       Input channels.
17
18
19       Since 4.14.0
20
21
22
23
24
25       type t = in_channel
26
27
28       The type of input channel.
29
30
31       type open_flag = open_flag =
32        | Open_rdonly  (* open for reading.
33        *)
34        | Open_wronly  (* open for writing.
35        *)
36        | Open_append  (* open for appending: always write at end of file.
37        *)
38        | Open_creat  (* create the file if it does not exist.
39        *)
40        | Open_trunc  (* empty the file if it already exists.
41        *)
42        | Open_excl  (* fail if Open_creat and the file already exists.
43        *)
44        | Open_binary  (* open in binary mode (no conversion).
45        *)
46        | Open_text  (* open in text mode (may perform conversions).
47        *)
48        | Open_nonblock  (* open in non-blocking mode.
49        *)
50
51
52       Opening modes for In_channel.open_gen .
53
54
55
56       val stdin : t
57
58       The standard input for the process.
59
60
61
62       val open_bin : string -> t
63
64       Open the named file for reading, and return a new input channel on that
65       file, positioned at the beginning of the file.
66
67
68
69       val open_text : string -> t
70
71       Same as In_channel.open_bin , but the file is opened in text  mode,  so
72       that newline translation takes place during reads. On operating systems
73       that do not distinguish between text mode and binary mode,  this  func‐
74       tion behaves like In_channel.open_bin .
75
76
77
78       val open_gen : open_flag list -> int -> string -> t
79
80
81       open_gen  mode  perm  filename opens the named file for reading, as de‐
82       scribed above. The extra arguments mode and perm  specify  the  opening
83       mode   and   file   permissions.    In_channel.open_text  and  In_chan‐
84       nel.open_bin are special cases of this function.
85
86
87
88       val with_open_bin : string -> (t -> 'a) -> 'a
89
90
91       with_open_bin fn f opens a channel ic on file fn and returns f
92           ic . After f returns, either with a value or by raising  an  excep‐
93       tion, ic is guaranteed to be closed.
94
95
96
97       val with_open_text : string -> (t -> 'a) -> 'a
98
99       Like  In_channel.with_open_bin , but the channel is opened in text mode
100       (see In_channel.open_text ).
101
102
103
104       val with_open_gen : open_flag list -> int -> string -> (t -> 'a) -> 'a
105
106       Like In_channel.with_open_bin , but can specify the  opening  mode  and
107       file  permission,  in  case  the  file  must  be  created (see In_chan‐
108       nel.open_gen ).
109
110
111
112       val seek : t -> int64 -> unit
113
114
115       seek chan pos sets the current reading position to pos for channel chan
116       .  This  works only for regular files. On files of other kinds, the be‐
117       havior is unspecified.
118
119
120
121       val pos : t -> int64
122
123       Return the current reading position for the given channel.   For  files
124       opened in text mode under Windows, the returned position is approximate
125       (owing to end-of-line conversion); in particular,  saving  the  current
126       position  with  In_channel.pos , then going back to this position using
127       In_channel.seek will not work.  For this programming idiom to work  re‐
128       liably and portably, the file must be opened in binary mode.
129
130
131
132       val length : t -> int64
133
134       Return the size (number of characters) of the regular file on which the
135       given channel is opened.  If the channel is opened on a  file  that  is
136       not  a regular file, the result is meaningless.  The returned size does
137       not take into account the end-of-line translations  that  can  be  per‐
138       formed when reading from a channel opened in text mode.
139
140
141
142       val close : t -> unit
143
144       Close  the  given channel.  Input functions raise a Sys_error exception
145       when they are applied  to  a  closed  input  channel,  except  In_chan‐
146       nel.close  , which does nothing when applied to an already closed chan‐
147       nel.
148
149
150
151       val close_noerr : t -> unit
152
153       Same as In_channel.close , but ignore all errors.
154
155
156
157       val input_char : t -> char option
158
159       Read one character from the given input channel.  Returns None if there
160       are no more characters to read.
161
162
163
164       val input_byte : t -> int option
165
166       Same as In_channel.input_char , but return the 8-bit integer represent‐
167       ing the character. Returns None if the end of file was reached.
168
169
170
171       val input_line : t -> string option
172
173
174       input_line ic reads characters from ic until a newline or  the  end  of
175       file  is  reached.   Returns the string of all characters read, without
176       the newline (if any).  Returns None if the end of  the  file  has  been
177       reached.   In particular, this will be the case if the last line of in‐
178       put is empty.
179
180       A newline is the character \n unless the file is open in text mode  and
181       Sys.win32 is true in which case it is the sequence of characters \r\n .
182
183
184
185       val input : t -> bytes -> int -> int -> int
186
187
188       input  ic buf pos len reads up to len characters from the given channel
189       ic , storing them in byte sequence buf , starting at  character  number
190       pos  .  It  returns the actual number of characters read, between 0 and
191       len (inclusive). A return value of 0 means that the  end  of  file  was
192       reached.
193
194       Use In_channel.really_input to read exactly len characters.
195
196
197       Raises  Invalid_argument  if pos and len do not designate a valid range
198       of buf .
199
200
201
202       val really_input : t -> bytes -> int -> int -> unit option
203
204
205       really_input ic buf pos len reads len  characters  from  channel  ic  ,
206       storing them in byte sequence buf , starting at character number pos .
207
208       Returns  None  if the end of file is reached before len characters have
209       been read.
210
211       If the same channel is read concurrently by multiple threads, the bytes
212       read by really_input are not guaranteed to be contiguous.
213
214
215       Raises  Invalid_argument  if pos and len do not designate a valid range
216       of buf .
217
218
219
220       val really_input_string : t -> int -> string option
221
222
223       really_input_string ic len reads len characters from channel ic and re‐
224       turns them in a new string.  Returns None if the end of file is reached
225       before len characters have been read.
226
227       If the same channel is read concurrently by multiple threads,  the  re‐
228       turned  string  is not guaranteed to contain contiguous characters from
229       the input.
230
231
232
233       val input_all : t -> string
234
235
236       input_all ic reads all remaining data from ic .
237
238       If the same channel is read concurrently by multiple threads,  the  re‐
239       turned  string  is not guaranteed to contain contiguous characters from
240       the input.
241
242
243
244       val set_binary_mode : t -> bool -> unit
245
246
247       set_binary_mode ic true sets the channel ic to binary mode: no transla‐
248       tions take place during input.
249
250
251       set_binary_mode ic false sets the channel ic to text mode: depending on
252       the operating system, some translations may take  place  during  input.
253       For  instance, under Windows, end-of-lines will be translated from \r\n
254       to \n .
255
256       This function has no effect under operating systems that do not distin‐
257       guish between text mode and binary mode.
258
259
260
261
262
263OCamldoc                          2023-07-20                     In_channel(3)