Assign: what changed

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

Title: Assign

New		Line
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	+
3	+	## Contents
4	+
5	+	* 1 usage
6	+	* 2 application
7	+	* 3 caveats
8	+	* 4 notes
9	+
10	+	## usage
11	+
12	+	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	+	```
14	+	program assignDemo(input, output, stdErr);
15	+	var
16	+	FD: text;
17	+	begin
18	+	assign(FD, '/tmp/assignDemo.txt');
19	+	assign(FD, '/root/.bashrc');
20	+	end.
21	+	```
22	+
23	+	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	+
25	+	## application
26	+
27	+	* `Assign` is used before operating on any file variable.
28	+	```
29	+	program assignApplication(input, output, stdErr);
30	+	var
31	+	executable: file of Byte;
32	+	begin
33	+	assign(executable, paramStr(0));
34	+	fileMode := 0; { 0 = read-only; only relevant for `file of …` variables }
35	+	reset(executable);
36	+	writeLn(paramStr(0), ' has a size of ', fileSize(executable), ' Bytes.');
37	+	end.
38	+	```
39	+
40	+	* `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	+	```
42	+	program redirectDemo(input, output, stdErr);
43	+	const
44	+	blackhole = {$ifDef Linux} '/dev/null' + {$endIf}
45	+	{$ifDef Windows} 'nul' + {$endIf}
46	+	'';
47	+	begin
48	+	assign(output, blackhole);
49	+	rewrite(output);
50	+	writeLn('Hello world!');
51	+	end.
52	+	```
53	+
54	+	## caveats
55	+
56	+	* 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	+	* 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	+
59	+	## notes
60	+
61	+	* 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	+	* In [[Extended Pascal]] a combination of `bindingType` and `bind` are usually used to achieve linking a file variable with an external entity.
63	+
64	+	---
65	+	From the Free Pascal wiki, page "AssignFile", as the Internet Archive kept it on 2025-05-17. 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