xHarbour Reference Documentation > Function Reference

HB_FCreate()

Creates and/or opens a binary file.

Syntax

HB_FCreate( <cFileName>, [<nFileAttr>], [<nOpenFlags>] ) --> nFileHandle

Arguments

<cFilename>

This is a character string holding the name of the file to create. It must include path and file extension. If the path is omitted from <cFileName>, the file is created in the current directory.

<nFileAttr>

A numeric value specifying one or more attributes associated with the created or opened file. #define constants from the FILEIO.CH file can be used for <nFileAttr> as listed in the table below:

Attributes for binary file creation

Constant	Value	Attribute	Description
FC_NORMAL *)	0	Normal	Creates a normal read/write file
FC_READONLY	1	Read-only	Creates a read-only file
FC_HIDDEN	2	Hidden	Creates a hidden file
FC_SYSTEM	4	System	Creates a system file
*) default attribute

<nOpenFlags>

A numeric value specifying one or more flags indication how to create a new or open an existing file #define constants from the FILEIO.CH file can be used for <nOpenFlags> as listed in the table below:

Flags for file opening or creation

Constant	Value	Description
FO_COMPAT *)	0	Compatibility mode
FO_EXCLUSIVE	16	Exclusive use
FO_DENYWRITE	32	Prevent other applications from writing
FO_DENYREAD	48	Prevent other applications from reading
FO_DENYNONE	64	Allow others to read or write
FO_SHARED	64	Same as FO_DENYNONE
FO_CREAT	0x0100	Create and open file
FO_TRUNC	0x0200	Open existing file and truncate it
FO_EXCL	0x0400	Create and open only if the file does not exist
*) default attribute

Return

The function returns a numeric file handle to be used later for accessing the file using FRead() or FWrite(). The return value is -1 when the operation fails. Use FError() to determine the cause of failure.

Description

The low-level file function HB_FCreate() is a combination of FCreate() and FOpen(). HB_FCreate() opens an existing file or creates a new one.

If <cFileName> specifys an existing file, the third parameter <nOpenFlags> can be used to indicate if the file should be truncated, i.e. all data should be removed from the file after opening.

Refer to FRead() and FWrite() for examples that read or write data to a binary file using a file handle returned from HB_FCreate().

Info

See also:	FCreate(), FOpen(), HB_FCommit(), HB_F_Eof()
Category:	File functions , Low level file functions , xHarbour extensions
Header:	FileIO.ch
Source:	rtl\philes.c
LIB:	xhb.lib
DLL:	xhbdll.dll