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