Stdlib.In_channel(3)

💖 Stdlib.In_channel(3) 💖

okay so bestie, welcome to the In_channel page from the OCaml library manual — this is the one about reading stuff. Channels that bring data into your program. Main character energy for sure 👑

---

✨ NAME ✨

Stdlib.In_channel — no description (yes, literally, the manpage says "no description" and I'm not gonna ghost you about it 🙈 we just vibe with it)

---

🦋 Module 🦋

Module Stdlib.In_channel

🎀 Documentation 🎀

Module In_channel : (module Stdlib__In_channel)

---

🌸 Channels 🌸

type t = in_channel

The type of an input channel, periodt. That's the thing you read from 💅

type open_flag = open_flag =
 | Open_rdonly  (* open for reading.
 *)
 | Open_wronly  (* open for writing.
 *)
 | Open_append  (* open for appending: always write at end of file.
 *)
 | Open_creat  (* create the file if it does not exist.
 *)
 | Open_trunc  (* empty the file if it already exists.
 *)
 | Open_excl  (* fail if Open_creat and the file already exists.
 *)
 | Open_binary  (* open in binary mode (no conversion).
 *)
 | Open_text  (* open in text mode (may perform conversions).
 *)
 | Open_nonblock  (* open in non-blocking mode.
 *)

These are the opening modes for In_channel.open_gen — the whole menu of flag combos, no cap 🍓

• Open_rdonly — open for reading.
• Open_wronly — open for writing.
• Open_append — open for appending: always write at end of file.
• Open_creat — create the file if it does not exist.
• Open_trunc — empty the file if it already exists.
• Open_excl — fail if Open_creat and the file already exists.
• Open_binary — open in binary mode (no conversion).
• Open_text — open in text mode (may perform conversions).
• Open_nonblock — open in non-blocking mode.

---

val stdin : t

The standard input for the process 🫶 the eternal vibe source.

val open_bin : string -> t

Open the named file for reading, and return a new input channel on that file, positioned at the beginning of the file. Binary mode, no translation, clean slate ✨

val open_text : string -> t

Same as In_channel.open_bin, but the file is opened in text mode, so that newline translation takes place during reads. On operating systems that do not distinguish between text mode and binary mode, this function behaves like In_channel.open_bin — iykyk, it's just a no-op there 💀

val open_gen : open_flag list -> int -> string -> t

open_gen mode perm filename opens the named file for reading, as described above. The extra arguments mode and perm specify the opening mode and file permissions. In_channel.open_text and In_channel.open_bin are special cases of this function — they're literally the nepo babies of open_gen 👑

val with_open_bin : string -> (t -> 'a) -> 'a

with_open_bin fn f opens a channel ic on file fn and returns f ic. After f returns — either with a value or by raising an exception — ic is guaranteed to be closed. Cleanup ate and left no crumbs 🙌

val with_open_text : string -> (t -> 'a) -> 'a

Like In_channel.with_open_bin, but the channel is opened in text mode (see In_channel.open_text).

val with_open_gen : open_flag list -> int -> string -> (t -> 'a) -> 'a

Like In_channel.with_open_bin, but can specify the opening mode and file permission, in case the file must be created (see In_channel.open_gen).

val close : t -> unit

Close the given channel. Input functions raise a Sys_error exception when they are applied to a closed input channel — except In_channel.close, which does nothing when applied to an already closed channel. Respectfully, she's unbothered 💅

val close_noerr : t -> unit

Same as In_channel.close, but ignore all errors. Errors? Never heard of her 🙈

---

🦄 Input 🦄

val input_char : t -> char option

Read one character from the given input channel. Returns None if there are no more characters to read.

val input_byte : t -> int option

Same as In_channel.input_char, but return the 8-bit integer representing the character. Returns None if the end of file was reached.

val input_line : t -> string option

input_line ic reads characters from ic until a newline or the end of file is reached. Returns the string of all characters read, without the newline (if any). Returns None if the end of the file has been reached. In particular, this will be the case if the last line of input is empty 😭

A newline is the character \n unless the file is open in text mode and Sys.win32 is true — in which case it is the sequence of characters \r\n. Windows moment fr fr 💀

val really_input_string : t -> int -> string option

really_input_string ic len reads len characters from channel ic and returns them in a new string. Returns None if the end of file is reached before len characters have been read.

🫶 heads up bestie: if the same channel is read concurrently by multiple threads, the returned string is not guaranteed to contain contiguous characters from the input. Threads said "we're all main characters here" and chaos ensued.

val input_all : t -> string

input_all ic reads all remaining data from ic. The whole thing. Devoured. Ate. 🔥

Same caveat as above: if the same channel is read concurrently by multiple threads, the returned string is not guaranteed to contain contiguous characters from the input.

val input_lines : t -> string list

input_lines ic reads lines using In_channel.input_line until the end of file is reached. It returns the list of all lines read, in the order they were read. The newline characters that terminate lines are not included in the returned strings. Empty lines produce empty strings 🎀

Since 5.1 ✨

---

💜 Advanced input 💜

val input : t -> bytes -> int -> int -> int

input ic buf pos len reads up to len characters from the given channel ic, storing them in byte sequence buf, starting at character number pos. It returns the actual number of characters read, between 0 and len (inclusive). A return value of 0 means that the end of file was reached. Zero = the end, no drama 💀

Use In_channel.really_input to read exactly len characters.

Raises Invalid_argument if pos and len do not designate a valid range of buf — so like, don't do that 🙈

val input_bigarray : t -> ('a, Bigarray.int8_unsigned_elt,
       Bigarray.c_layout) Bigarray.Array1.t -> int -> int -> int

Same as In_channel.input, but read the data into a bigarray. Bigarray girlies rise 🌈

Since 5.2

val really_input : t -> bytes -> int -> int -> unit option

really_input ic buf pos len reads len characters from channel ic, storing them in byte sequence buf, starting at character number pos.

Returns None if the end of file is reached before len characters have been read.

⚠️ If the same channel is read concurrently by multiple threads, the bytes read by really_input are not guaranteed to be contiguous.

Raises Invalid_argument if pos and len do not designate a valid range of buf.

val really_input_bigarray : t -> ('a, Bigarray.int8_unsigned_elt,
       Bigarray.c_layout) Bigarray.Array1.t -> int -> int -> unit option

Same as In_channel.really_input, but read the data into a bigarray.

Since 5.2

val fold_lines : ('acc -> string -> 'acc) -> 'acc -> t -> 'acc

fold_lines f init ic reads lines from ic using In_channel.input_line until the end of file is reached, and successively passes each line to function f in the style of a fold 🧚

More precisely, if lines l1, ..., lN are read, fold_lines f init ic computes f (... (f (f init l1) l2) ...) lN.

If f has no side effects, this is equivalent to List.fold_left f init (In_channel.input_lines ic), but is more efficient since it does not construct the list of all lines read. Efficiency slay 💅

Since 5.1

---

🔍 Seeking 🔍

val seek : t -> int64 -> unit

seek chan pos sets the current reading position to pos for channel chan. This works only for regular files. On files of other kinds, the behavior is unspecified — which is devspeak for "good luck bestie, you're on your own" 💀🚩

val pos : t -> int64

Return the current reading position for the given channel. For files opened in text mode under Windows, the returned position is approximate (owing to end-of-line conversion); in particular, saving the current position with In_channel.pos, then going back to this position using In_channel.seek will not work. For this programming idiom to work reliably and portably, the file must be opened in binary mode. Lesson learned fr fr 📚

---

⭐ Attributes ⭐

val length : t -> int64

Return the size (number of characters) of the regular file on which the given channel is opened. If the channel is opened on a file that is not a regular file, the result is meaningless 🫠 The returned size does not take into account the end-of-line translations that can be performed when reading from a channel opened in text mode.

val set_binary_mode : t -> bool -> unit

set_binary_mode ic true sets the channel ic to binary mode: no translations take place during input.

set_binary_mode ic false sets the channel ic to text mode: depending on the operating system, some translations may take place during input. For instance, under Windows, end-of-lines will be translated from \r\n to \n 🪟

This function has no effect under operating systems that do not distinguish between text mode and binary mode — literally nothing happens, she's just standing there 💅

val is_binary_mode : t -> bool

is_binary_mode ic returns whether the channel ic is in binary mode (see In_channel.set_binary_mode). Vibe check on the mode ✨

Since 5.2

val isatty : t -> bool

isatty ic is true if ic refers to a terminal or console window, false otherwise. Is it a real tty or just pretending 🎭

Since 5.1

---

🌈 Examples 🌈

Reading the contents of a file — the classic:

let read_file file = In_channel.with_open_bin file In_channel.input_all

Reading a line from stdin — peak interactive energy:

let user_input () = In_channel.input_line In_channel.stdin

---

🫶 ok that's the whole page bestie, nothing skipped, every flag and caveat accounted for. now go read some files, you icon 👑

---

OCamldoc ✨ 2026-06-22 ✨ Stdlib.In_channel(3) — mwah, that's the version and date from the footer, love you, bye 💖🎀🦋