File Handling In Pascal: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Overview
2	2
3	3		Something every programmer needs to know is how to work with files. Files are used to persist data i.e. store data in such a way that it can be retrieved at a later time, without having to recreate it. Files can be used to store user settings, error logs, measurement or calculation results, and more. This page explains the basics of file handling.
4	4
5	5		## Old procedural style
6	6
7	7		When using files in classic (non-object oriented) Pascal, you can use a file of type TextFile (or simply Text) to store text, that is typically structured in lines. Every line ends with an end-of-line marker ([[End of Line\|LineEnding]]). You can store strings in this type of file, but also numbers which can be formatted in different ways. These files can be opened and edited inside the Lazarus IDE or any other text editor.
8	8
9	9		For specific purposes you can create your own file type that can only store one type of data. For example:
10	10
11	11		``` pascal
12	12		...
13	13		type
14	14		TIntegerFile = file of integer; // Allows you to write only integer numbers to the file
15	15		TExtendedFile = file of extended; // Allows you to write only real numbers to the file
16	16		TCharFile = file of char; // Allows you to write only single characters to the file
17	17		```
18	18
19	19		### Input/Output error handling
20	20
21	21		The [I/O error handling flag](http://www.freepascal.org/docs-html/prog/progsu38.html#x45-440001.2.38) tells the compiler how to deal with error situations: raise an exception or store the I/O result in the IOResult variable. The I/O error handling flag is a compiler directive. To enable or disable it:
22	22
23	23		``` pascal
24	24		{$I+} // Errors will lead to an EInOutError exception (default)
25	25		{$I-} // Suppress I/O errors: check the IOResult variable for the error code
26	26		```
27	27
28	28		By suppressing I/O errors ({\$I-}) the file operation results go into the IOResult variable. This is a [[Cardinal\|cardinal (number) type]]. Different numbers mean different errors. So you may want to check the documentation for the different errors[1](http://www.freepascal.org/docs-html/rtl/system/ioresult.html).
29	29
30	30		### File procedures
31	31
32	32		These file handling procedures and functions are located in [[System unit\|unit System]]. See the FPC documentation for more details: [Reference for 'System' unit](http://www.freepascal.org/docs-html/rtl/system/index-5.html).
33	33
34	34		- AssignFile (prevent the use of the older [[Assign]] procedure) - Assign a name to a file
35	35		- Append - Opens an existing file for appending data to end of file and editing it
36	36		- BlockRead - Read data from an untyped file into memory
37	37		- BlockWrite - Write data from memory to an untyped file
38	38		- CloseFile (prevent the use of the older Close procedure) - Close opened file
39	39		- EOF - Check for end of file
40	40		- Erase - Erase file from disk
41	41		- FilePos - Get position in file
42	42		- FileSize - Get size of file
43	43		- Flush - Write file buffers to disk
44	44		- IOResult - Return result of last file IO operation
45	45		- Read - Read from a text file
46	46		- ReadLn - Read from a text file and go to the next line
47	47		- Reset - Opens a file for reading
48	48		- Rewrite - Create a file for writing
49	49		- Seek - Change position in file
50	50		- SeekEOF - Set file position to end of file
51	51		- SeekEOLn - Set file position to end of line
52	52		- Truncate - Truncate the file at position
53	53		- [[Write]] - Write variable to a file
54	54		- WriteLn - Write variable to a text file and go to a new line
55	55
56	56		### Example
57	57
58	58		A full example of handling a text file of type TextFile:
59	59
60	60		``` pascal
61	61		program CreateFile;
62	62
63	63		{$mode objfpc}
64	64
65	65		uses
66	66		Sysutils;
67	67
68	68		const
69	69		C_FNAME = 'textfile.txt';
70	70
71	71		var
72	72		tfOut: TextFile;
73	73
74	74		begin
75	75		// Set the name of the file that will be created
76	76		AssignFile(tfOut, C_FNAME);
77	77
78	78		// Use exceptions to catch errors (this is the default so not absolutely requried)
79	79		{$I+}
80	80
81	81		// Embed the file creation in a try/except block to handle errors gracefully
82	82		try
83	83		// Create the file, write some text and close it.
84	84		rewrite(tfOut);
85	85
86	86		writeln(tfOut, 'Hello textfile!');
87	87		writeln(tfOut, 'The answer to life, the universe and everything: ', 42);
88	88
89	89		CloseFile(tfOut);
90	90
91	91		except
92	92		// If there was an error the reason can be found here
93	93		on E: EInOutError do
94	94		writeln('File handling error occurred. Details: ', E.ClassName, '/', E.Message);
95	95		end;
96	96
97	97		// Give feedback and wait for key press
98	98		writeln('File ', C_FNAME, ' created if all went ok. Press Enter to stop.');
99	99		readln;
100	100		end.
101	101		```
102	102
103	103		Now open the file in any text editor and you will see the above text written to it! You can test the error handling by running the program once, then set the file to read-only and run the program again.
104	104
105	105		Note that exception handling was used as that is an easy way to perfom multiple file operations and handling the errors. You could also use {\$I-}, but then you would have to check IOResult after each operation and modify your next operation.
106	106
107	107		Here's how appending more text to a textfile works:
108	108
109	109		``` pascal
110	110		program AppendToFile;
111	111
112	112		{$mode objfpc}
113	113
114	114		uses
115	115		Sysutils;
116	116
117	117		const
118	118		C_FNAME = 'textfile.txt';
119	119
120	120		var
121	121		tfOut: TextFile;
122	122
123	123		begin
124	124		// Set the name of the file that will receive some more text
125	125		AssignFile(tfOut, C_FNAME);
126	126
127	127		// Embed the file handling in a try/except block to handle errors gracefully
128	128		try
129	129		// Open the file for appending, write some more text to it and close it.
130	130		append(tfOut);
131	131
132	132		writeln(tfOut, 'Hello again textfile!');
133	133		writeln(tfOut, 'The result of 6 * 7 = ', 6 * 7);
134	134
135	135		CloseFile(tfOut);
136	136
137	137		except
138	138		on E: EInOutError do
139	139		writeln('File handling error occurred. Details: ', E.Message);
140	140		end;
141	141
142	142		// Give feedback and wait for key press
143	143		writeln('File ', C_FNAME, ' might have more text. Press enter to stop.');
144	144		readln;
145	145		end.
146	146		```
147	147
148	148		Reading a textfile:
149	149
150	150		``` pascal
151	151		program ReadFile;
152	152
153	153		{$mode objfpc}
154	154
155	155		uses
156	156		Sysutils;
157	157
158	158		const
159	159		C_FNAME = 'textfile.txt';
160	160
161	161		var
162	162		tfIn: TextFile;
163	163		s: string;
164	164
165	165		begin
166	166		// Give some feedback
167	167		writeln('Reading the contents of file: ', C_FNAME);
168	168		writeln('=========================================');
169	169
170	170		// Set the name of the file that will be read
171	171		AssignFile(tfIn, C_FNAME);
172	172
173	173		// Embed the file handling in a try/except block to handle errors gracefully
174	174		try
175	175		// Open the file for reading
176	176		reset(tfIn);
177	177
178	178		// Keep reading lines until the end of the file is reached
179	179		while not eof(tfIn) do
180	180		begin
181	181		readln(tfIn, s);
182	182		writeln(s);
183	183		end;
184	184
185	185		// Done so close the file
186	186		CloseFile(tfIn);
187	187
188	188		except
189	189		on E: EInOutError do
190	190		writeln('File handling error occurred. Details: ', E.Message);
191	191		end;
192	192
193	193		// Wait for the user to end the program
194	194		writeln('=========================================');
195	195		writeln('File ', C_FNAME, ' was probably read. Press enter to stop.');
196	196		readln;
197	197		end.
198	198		```
199	199
200	200		## Object style
201	201
202	202		In addition to the old style file handling routines mentioned above, a new system exists that uses the concept of streams (- of data) at a higher abstraction level. This means data can be read from or written to any location (disk, memory, hardware ports etc.) by one uniform interface.
203	203
204	204		In addition, most string handling classes have the ability to load and save content from/to a file. These methods are usually named SaveToFile and LoadFromFile. A lot of other objects (such as Lazarus grids) have similar functionality, including Lazarus datasets (DBExport). It pays to look through the documentation or source code before trying to roll your own save/load routines.
205	205
206	206		### Generic files of any type
207	207
208	208		For opening files for direct access TFileStream can be used. This class is an encapsulation of the system procedures FileOpen, FileCreate, FileRead, FileWrite, FileSeek and FileClose which resides in unit SysUtils.
209	209
210	210		[IO routines](http://www.freepascal.org/docs-html/rtl/sysutils/ioroutines.html)
211	211
212	212		Here is a very simple example of appending one file to another using streams. It is equivalent to the append example above, but much simpler:
213	213
214	214		``` pascal
215	215		program InOutStream;
216	216
217	217		{$mode objfpc}
218	218
219	219		uses
220	220		Classes, SysUtils;
221	221		var
222	222		InStream, OutStream: TFileStream;
223	223		begin
224	224		if (ParamCount = 2) and
225	225		FileExists(ParamStr(1)) and
226	226		FileExists(ParamStr(2)) then
227	227		begin
228	228		InStream := TFileStream.Create(ParamStr(1), fmOpenRead);
229	229		try
230	230		OutStream := TFileStream.Create(Paramstr(2), fmOpenWrite);
231	231		try
232	232		OutStream.Position := OutStream.size;
233	233		OutStream.CopyFrom(InStream, 0); // appends
234	234		finally
235	235		OutStream.Free;
236	236		end;
237	237		finally
238	238		InStream.Free;
239	239		end;
240	240		end else
241	241		Writeln('Usage: inoutstream <infile> <outfile>');
242	242		end.
243	243		```
244	244
245		-	\
246	245		In the example below, note how we encapsulate the file handling action with a try..except block so that errors are handled correctly just as with the classic file handling routines (as not to convolute the example the fsOut.write is not put inside a try...finally block).
247	246
248	247		``` pascal
249	248		program WriteBinaryData;
250	249
251	250		{$mode objfpc}
252	251
253	252		uses
254	253		Classes, Sysutils;
255	254
256	255		const
257	256		C_FNAME = 'binarydata.bin';
258	257
259	258		var
260	259		fsOut : TFileStream;
261	260		ChrBuffer: array[0..2] of char;
262	261
263	262		begin
264	263		// Set up some random data that will get stored
265	264		ChrBuffer[0] := 'A';
266	265		ChrBuffer[1] := 'B';
267	266		ChrBuffer[2] := 'C';
268	267
269	268		// Catch errors in case the file cannot be created
270	269		try
271	270		// Create the file stream instance, write to it and free it to prevent memory leaks
272	271		fsOut := TFileStream.Create( C_FNAME, fmCreate);
273	272		fsOut.Write(ChrBuffer, sizeof(ChrBuffer));
274	273		fsOut.Free;
275	274
276	275		// Handle errors
277	276		except
278	277		on E:Exception do
279	278		writeln('File ', C_FNAME, ' could not be created because: ', E.Message);
280	279		end;
281	280
282	281		// Give feedback and wait for key press
283	282		writeln('File ', C_FNAME, ' created if all went ok. Press Enter to stop.');
284	283		readln;
285	284		end.
286	285		```
287	286
288	287		You can load entire files into memory too if its size is comparatively smaller than available system memory. Bigger sizes might work but your operating system will start using the page/swap file, making the exercise useless from a performance standpoint.
289	288
290	289		``` pascal
291	290		program ReadBinaryDataInMemoryForAppend;
292	291
293	292		{$mode objfpc}
294	293
295	294		uses
296	295		Classes, Sysutils;
297	296
298	297		const
299	298		C_FNAME = 'binarydata.bin';
300	299
301	300		var
302	301		msApp: TMemoryStream;
303	302
304	303		begin
305	304		// Set up the stream
306	305		msApp := TMemoryStream.Create;
307	306
308	307		// Catch errors in case the file cannot be read or written
309	308		try
310	309		// Read the data into memory
311	310		msApp.LoadFromFile(C_FNAME);
312	311
313	312		// Seek the end of the stream so data can be appended
314	313		msApp.Seek(0, soEnd);
315	314
316	315		// Write some arbitrary data to the memory stream
317	316		msApp.WriteByte(68);
318	317		msApp.WriteAnsiString('Some extra text');
319	318		msApp.WriteDWord(671202);
320	319
321	320		// Store the data back on disk, overwriting the previous contents
322	321		msApp.SaveToFile(C_FNAME);
323	322
324	323		// Handle errors
325	324		except
326	325		on E:Exception do
327	326		writeln('File ', C_FNAME, ' could not be read or written because: ', E.Message);
328	327		end;
329	328
330	329		// Clean up
331	330		msApp.Free;
332	331
333	332		// Give feedback and wait for key press
334	333		writeln('File ', C_FNAME, ' was extended if all went ok. Press Enter to stop.');
335	334		readln;
336	335		end.
337	336		```
338	337
339	338		With larger files of many Gb, you may want to read in buffers of, say, 4096 bytes (you're advised to use a multiple of the filesytem cluster or block size) and do something with the data of each buffer read.
340	339
341	340		``` pascal
342	341		var
343	342		TotalBytesRead, BytesRead : Int64;
344	343		Buffer : array [0..4095] of byte; // or, array [0..4095] of char
345	344		FileStream : TFileStream;
346	345
347	346		try
348	347		FileStream := TFileStream.Create;
349	348		FileStream.Position := 0; // Ensure you are at the start of the file
350	349		TotalBytesRead := 0;
351	350		while TotalBytesRead <= FileStream.Size do // While the amount of data read is less than or equal to the size of the stream do
352	351		begin
353	352		BytesRead := FileStream.Read(Buffer, SizeOf(Buffer)); // Read in 4096 of data
354	353		Inc(TotalBytesRead, BytesRead); // Increase TotalByteRead by the size of the buffer, i.e. 4096 bytes
355	354		// Do something with Buffer data
356	355		end;
357	356		```
358	357
359	358		### FileCopy
360	359
361	360		With the above, we can implement a simple FileCopy function (FreePascal has none in its RTL although Lazarus has [[CopyFile]]) - adjust as needed for bigger files etc:
362	361
363	362		``` pascal
364	363		program FileCopyDemo;
365	364		// Demonstration of FileCopy function
366	365
367	366		{$mode objfpc}
368	367
369	368		uses
370	369		Classes;
371	370
372	371		const
373	372		fSource = 'test.txt';
374	373		fTarget = 'test.bak';
375	374
376	375		function FileCopy(Source, Target: string): boolean;
377	376		// Copies source to target; overwrites target.
378	377		// Caches entire file content in memory.
379	378		// Returns true if succeeded; false if failed.
380	379		var
381	380		MemBuffer: TMemoryStream;
382	381		begin
383	382		Result := false;
384	383		MemBuffer := TMemoryStream.Create;
385	384		try
386	385		MemBuffer.LoadFromFile(Source);
387	386		MemBuffer.SaveToFile(Target);
388	387		Result := true
389	388		except
390	389		//swallow exception; function result is false by default
391	390		end;
392	391		// Clean up
393	392		MemBuffer.Free
394	393		end;
395	394
396	395		begin
397	396		If FileCopy(fSource, fTarget)
398	397		then Writeln('File ', fSource, ' copied to ', fTarget)
399	398		else Writeln('File ', fSource, ' not copied to ', fTarget);
400	399		Readln()
401	400		end.
402	401		```
403	402
404	403		### Handling Text files (TStringList)
405	404
406	405		In general, for text files you can use the TStringList class to load the entire file into memory and have easy access to its lines. Of course, you can also write the StringList back to a file:
407	406
408	407		``` pascal
409	408		program StringListDemo;
410	409
411	410		{$mode objfpc}
412	411
413	412		uses
414	413		Classes, SysUtils;
415	414
416	415		const
417	416		C_FNAME = 'textfile.txt';
418	417
419	418		var
420	419		slInfo: TStringList;
421	420
422	421		begin
423	422		// Create an instance of the string list to handle the textfile
424	423		slInfo := TStringList.Create;
425	424
426	425		// Embed the file handling in a try/except block to handle errors gracefully
427	426		try
428	427		// Load the contents of the textfile completely in memory
429	428		slInfo.LoadFromFile(C_FNAME);
430	429
431	430		// Add some more contents
432	431		slInfo.Add('An extra line appended to the text');
433	432		slInfo.Add('And another one.');
434	433		slInfo.Add('Let''s stop here.');
435	434		slInfo.Add('It is now ' + DateTimeToStr(now));
436	435
437	436		// And write the contents back to disk, replacing the original contents
438	437		slInfo.SaveToFile(C_FNAME);
439	438
440	439		except
441	440		// If there was an error the reason can be found here
442	441		on E: EInOutError do
443	442		writeln('File handling error occurred. Reason: ', E.Message);
444	443		end;
445	444
446	445		// Clean up
447	446		slInfo.Free;
448	447
449	448		// Give feedback and wait for key press
450	449		writeln('File ', C_FNAME, ' updated if all went ok. Press Enter to stop.');
451	450		readln;
452	451		end.
453	452		```
454	453
455	454		### Demo: save single string to a file
456	455
457	456		In order to write a single string to a stream you might want to use the procedure defined below. Note that strings in FreePascal can be extremely long, this is also a useful way to write a big block of textdata to a file.
458	457
459	458		``` pascal
460	459		program SaveStringToPathDemo;
461	460
462	461		{$mode objfpc}
463	462
464	463		uses
465	464		Classes, sysutils;
466	465
467	466		const
468	467		C_FNAME = 'textstringtofile.txt';
469	468
470	469		// SaveStringToFile: function to store a string of text into a diskfile.
471	470		// If the function result equals true, the string was written ok.
472	471		// If not then there was some kind of error.
473	472		function SaveStringToFile(theString, filePath: AnsiString): boolean;
474	473		var
475	474		fsOut: TFileStream;
476	475		begin
477	476		// By default assume the writing will fail.
478	477		result := false;
479	478
480	479		// Write the given string to a file, catching potential errors in the process.
481	480		try
482	481		fsOut := TFileStream.Create(filePath, fmCreate);
483	482		fsOut.Write(theString[1], length(theString));
484	483		fsOut.Free;
485	484
486	485		// At his point it is known that the writing went ok.
487	486		result := true
488	487
489	488		except
490	489		on E:Exception do
491	490		writeln('String could not be written. Details: ', E.ClassName, ': ', E.Message);
492	491		end
493	492		end;
494	493
495	494		//
496	495		// Main program
497	496		//
498	497		begin
499	498		// Try to save a simple textstring in a file and give feedback of sucess.
500	499		if SaveStringToFile('>> this text gets stored <<', C_FNAME) then
501	500		writeln('Text succesfully written to a file')
502	501		else
503	502		writeln('Writing text to a file failed.');
504	503
505	504		// Wait for the user to press Enter
506	505		readln
507	506		end.
508	507		```
509	508
510	509		## File Handling in ISO Mode
511	510
512	511		### Command Line Parameters
513	512
514	513		The first option to assign external to internal files in iso mode is through command line parameters according to their order of appearance. Example:
515	514
516	515		``` pascal
517	516		program isotest1 (file1, file2);
518	517		var
519	518		file1: text;
520	519		file2: file of integer;
521	520		begin
522	521		reset(file1);
523	522		readln(file1);
524	523		rewrite(file2);
525	524		write(file2, 5);
526	525		end.
527	526		```
528	527
529	528		The program is compiled with `fpc -Miso isotest1.pas` and run with `./isotest1 external1.txt external2.dat`. files1 is assigned to external1.txt and file2 to external2.dat. Without command line parameters the files are assigned to stdin and stdout. As long as there is only one file for input and one for output, the same assignment can be achieved with this command: `./isotest1 <external1.txt >external2.dat`. file1 must exist prior to the run, file2 will be created.
530	529
531	530		### Transparent File Names
532	531
533	532		The second option is transparent file names, achieved with the compiler option -Sr. Example:
534	533
535	534		``` pascal
536	535		program isotest2 (file1, file2);
537	536		var
538	537		file1: text;
539	538		file2: text;
540	539		begin
541	540		reset(file1);
542	541		readln(file1);
543	542		rewrite(file2);
544	543		write(file2, 5);
545	544		end.
546	545		```
547	546
548	547		If the program is compiled with `fpc -Miso -Sr isotest2.pas` and run without command line parameters, the external files FILE1.txt and FILE2.txt are read and written. Note the uppercase conversion of the internal filenames. Files with different filenames can still be used through command line parameters.
549	548
550	549		## See also
551	550
552	551		- [[CopyFile]] Lazarus function (also available for command line programs) that copies files for you
553	552		- [[File]]
554	553		- [[Howto Use TOpenDialog]]
555	554		- [[Howto Use TSaveDialog]]
556	555
557	556		---
558	557		From the Free Pascal wiki, page "File Handling In Pascal", as it stood on 2023-10-12 after a change by FPC user, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history