Assign: what changed

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

Old	New		Line
1	1		The [[Borland Pascal]] [[Procedure\|`procedure`]] [`assign`](<https://www.freepascal.org/docs-html/rtl/system/assign.html>) associates a file variable with an external entity (e. g. a device file or a file on disk). `Assign` only operates on the program’s internal management data and has otherwise no immediate observable effect.
2	2
3		-	~~## Contents~~
4		-
5		-	* 1 usage
6		-	* 2 application
7		-	* 3 caveats
8		-	* 4 notes
9		-
10	3		## usage
11	4
12	5		In non-ISO modes the [[FPC]] needs files to be explicitly associated with external entities. This can be achieved with `assign`. The first parameter is a file variable, the second parameter specifies a path.
13	6		```
14	7		program assignDemo(input, output, stdErr);
15	8		var
16	9		FD: text;
17	10		begin
18	11		assign(FD, '/tmp/assignDemo.txt');
19	12		assign(FD, '/root/.bashrc');
20	13		end.
21	14		```
22	15
23	16		Note, you can run this program without any troubles as any user on any platform. Nonexistent path components (e. g. directories), missing privileges to eventually access the file or any path component, or unacceptable characters (usually [[Chr\|`chr(0)`]]) do not pose a problem to `assign`. It merely operates on internal management data.
24	17
25	18		## application
26	19
27	20		* `Assign` is used before operating on any file variable.
28	21		```
29	22		program assignApplication(input, output, stdErr);
30	23		var
31	24		executable: file of Byte;
32	25		begin
33	26		assign(executable, paramStr(0));
34	27		fileMode := 0; { 0 = read-only; only relevant for `file of …` variables }
35	28		reset(executable);
36	29		writeLn(paramStr(0), ' has a size of ', fileSize(executable), ' Bytes.');
37	30		end.
38	31		```
39	32
40	33		* `Assign` can be used to _redirect_ standard files [`input`](<https://www.freepascal.org/docs-html/rtl/system/input.html>)/[`output`](<https://www.freepascal.org/docs-html/rtl/system/output.html>). Our [[Hello, World]] program needs only a few changes as highlighted:
41	34		```
42	35		program redirectDemo(input, output, stdErr);
43	36		const
44	37		blackhole = {$ifDef Linux} '/dev/null' + {$endIf}
45	38		{$ifDef Windows} 'nul' + {$endIf}
46	39		'';
47	40		begin
48	41		assign(output, blackhole);
49	42		rewrite(output);
50	43		writeLn('Hello world!');
51	44		end.
52	45		```
53	46
54	47		## caveats
55	48
56	49		* Regardless of the utilized [[Character and string types\|string data type]], `assign` can only process paths of up to 255 [[Byte\|Bytes]]. This limitation comes from the internally used [`fileRec`](<https://www.freepascal.org/docs-html/rtl/system/filerec.html>)/[`textRec`](<https://www.freepascal.org/docs-html/rtl/system/textrec.html>). Relative paths in conjunction with working directories cannot overcome this. Cf. [FPC issue 35185](<https://gitlab.com/freepascal.org/fpc/source/-/issues/35185>).
57	50		* Since `assign` only operates on internal management data, specifying illegal paths is accepted. It is even possible to supply an empty string as a path. The specific behavior on a file variable bearing an empty file name depends on the used I/O routine.
58	51
59	52		## notes
60	53
61	54		* If `{$modeSwitch objPas+}` (automatically set via [[Mode ObjFPC\|`{$mode objFPC}`]] or [[Mode Delphi\|`{$mode Delphi}`]]), the `procedure` `assignFile` is available, too. It performs the very same task.
62	55		* In [[Extended Pascal]] a combination of `bindingType` and `bind` are usually used to achieve linking a file variable with an external entity.
63	56
64	57		---
65	58		From the Free Pascal wiki, page "AssignFile", as the Internet Archive kept it on 2025-05-17, last changed on 2022-09-03. 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