open_fileT_open_fileOpenFileOpenFile (Operator)


open_fileT_open_fileOpenFileOpenFile — Open a file in text or binary format.


open_file( : : FileName, FileType : FileHandle)

Herror T_open_file(const Htuple FileName, const Htuple FileType, Htuple* FileHandle)

void OpenFile(const HTuple& FileName, const HTuple& FileType, HTuple* FileHandle)

void HFile::HFile(const HString& FileName, const HTuple& FileType)

void HFile::HFile(const HString& FileName, const HString& FileType)

void HFile::HFile(const char* FileName, const char* FileType)

void HFile::HFile(const wchar_t* FileName, const wchar_t* FileType)   (Windows only)

void HFile::OpenFile(const HString& FileName, const HTuple& FileType)

void HFile::OpenFile(const HString& FileName, const HString& FileType)

void HFile::OpenFile(const char* FileName, const char* FileType)

void HFile::OpenFile(const wchar_t* FileName, const wchar_t* FileType)   (Windows only)

static void HOperatorSet.OpenFile(HTuple fileName, HTuple fileType, out HTuple fileHandle)

public HFile(string fileName, HTuple fileType)

public HFile(string fileName, string fileType)

void HFile.OpenFile(string fileName, HTuple fileType)

void HFile.OpenFile(string fileName, string fileType)


open_fileopen_fileOpenFileOpenFileOpenFile opens a file in text format or in binary format. The name of the file is defined by the parameter FileNameFileNameFileNameFileNamefileName. The operator open_fileopen_fileOpenFileOpenFileOpenFile returns a handle to the file in the output parameter FileHandleFileHandleFileHandleFileHandlefileHandle. The parameter FileTypeFileTypeFileTypeFileTypefileType determines the type of the file. For text files this parameter can also be used to specify the encoding used for strings in that file, where besides UTF-8 only the local-8-bit encoding is supported.

The following settings for FileTypeFileTypeFileTypeFileTypefileType are supported:


An already existing input file is opened for reading in text format.


A new output file is opened for writing in text format.


An already existing output file is opened for writing at the end of the file in text format.


An already existing input file is opened for reading in binary format.


A new output file is opened for writing in binary format.


An already existing output file is opened for writing at the end of the file in binary format.

For text files the tuple passed to FileTypeFileTypeFileTypeFileTypefileType can be extended by one of the following encoding settings:


Strings in the file are encoded in UTF-8. This is the default, so for UTF-8 encoded files and all files which use only pure 7-bit US-ASCII characters this value can be omitted.


Strings in the file are encoded in the local-8-bit encoding which depends on the system's current locale setting. Valid encodings are defined, e.g., under Windows by the code pages 1252 (a Microsoft dialect of Latin-1) or 932 (Shift-JIS) or on Linux by the locales en_US.utf8, de_DE.iso885915, or ja_JP.sjis.


The encoding of the strings that are read from the file or written into it is not handled. In that mode multi-byte characters are neither processed nor interpreted, the operator fread_charfread_charFreadCharFreadCharFreadChar returns always one byte, and separator characters that depend on a specific locale are not handled in fread_linefread_lineFreadLineFreadLineFreadLine and fread_stringfread_stringFreadStringFreadStringFreadString. Furthermore, the strings are not transcoded into or from the current encoding of the HALCON library.

Note: Strings are still transcoded in the HALCON C/C++ interface, when the encoding of the HALCON C/C++ interface differs from the encoding of the HALCON library. For HDevelop scripts, the encoding is always set to UTF-8. To avoid transcoding of strings to HDevelop, the encoding of the HALCON library should be set to UTF-8.

For the standard terminal input and output streams, the file names 'standard'"standard""standard""standard""standard" ('input'"input""input""input""input" and 'output'"output""output""output""output") and 'error'"error""error""error""error" (only 'output'"output""output""output""output") are reserved.

Execution Information

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.


FileNameFileNameFileNameFileNamefileName (input_control)  filename HTupleHTupleHtuple (string) (string) (HString) (char*)

Name of file to be opened.

Default value: 'standard' "standard" "standard" "standard" "standard"

Suggested values: 'standard'"standard""standard""standard""standard", 'error'"error""error""error""error", '/tmp/dat.dat'"/tmp/dat.dat""/tmp/dat.dat""/tmp/dat.dat""/tmp/dat.dat"

FileTypeFileTypeFileTypeFileTypefileType (input_control)  string(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Type of file access and optional the string encoding.

Default value: 'output' "output" "output" "output" "output"

List of values: 'append'"append""append""append""append", 'append_binary'"append_binary""append_binary""append_binary""append_binary", 'ignore_encoding'"ignore_encoding""ignore_encoding""ignore_encoding""ignore_encoding", 'input'"input""input""input""input", 'input_binary'"input_binary""input_binary""input_binary""input_binary", 'locale_encoding'"locale_encoding""locale_encoding""locale_encoding""locale_encoding", 'output'"output""output""output""output", 'output_binary'"output_binary""output_binary""output_binary""output_binary", 'utf8_encoding'"utf8_encoding""utf8_encoding""utf8_encoding""utf8_encoding"

FileHandleFileHandleFileHandleFileHandlefileHandle (output_control)  file HFile, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

File handle.

Example (HDevelop)

* Creating an output text file with the name '/tmp/log.txt' and writing
* of a string:
   fwrite_string(FileHandle,'these are the first and last lines')


If the parameters are valid, the operator open_fileopen_fileOpenFileOpenFileOpenFile returns the value 2 (H_MSG_TRUE). If necessary, an exception is raised.

Possible Successors

fwrite_stringfwrite_stringFwriteStringFwriteStringFwriteString, fread_charfread_charFreadCharFreadCharFreadChar, fread_stringfread_stringFreadStringFreadStringFreadString, fread_linefread_lineFreadLineFreadLineFreadLine, fread_serialized_itemfread_serialized_itemFreadSerializedItemFreadSerializedItemFreadSerializedItem, fwrite_serialized_itemfwrite_serialized_itemFwriteSerializedItemFwriteSerializedItemFwriteSerializedItem, fread_bytesfread_bytesFreadBytesFreadBytesFreadBytes, fwrite_bytesfwrite_bytesFwriteBytesFwriteBytesFwriteBytes, close_fileclose_fileCloseFileCloseFileCloseFile

See also