PUT（文件I/O）

• 来源: https://www.freebasic.net/wiki/wikka.php?wakka=KeyPgPutfileio
• 最后更新: 2025-06-01

---

将缓冲区中的数据写入文件

语法

Put #filenum As long, [position As longint], data As Any [, amount As Uinteger]
Put #filenum As long, [position As longint], data As String
Put #filenum As long, [position As longint], data() As Any

用法

Put #filenum, position, data [, amount]
varres = Put (#filenum, position, data [, amount])

参数

filenum

打开文件时传递给 Open 的值。

position

Put 必须在文件中开始的位置。如果文件以 For Random 方式打开，位置以记录为单位，否则以字节为单位。如果省略，则从当前文件指针位置开始写入。位置从 1 开始：即文件的第一条记录或第一个字节位于位置 1。

如果 position 被省略或为零（0），文件写入将从当前文件位置开始。

data

写入数据的缓冲区。可以是数值变量、字符串、数组或用户自定义类型（包括通过 This 引用的）。该操作将尝试将整个变量传输到磁盘，除非给出了 amount。对于用户自定义类型实例，受影响的数据仅是非静态数据成员。

写入数组时，data 后面应跟一对空括号：'()'。Put 将写入数组中的所有数据。不允许使用 amount。

写入 String 时，写入的字节数与字符串数据中的字节数相同。不允许使用 amount。

注意：如果要从缓冲区写入值，不应传递指向缓冲区的指针；而应传递缓冲区中的第一个变量（可以通过用 Operator * (Value of) 解引用指针来完成）。如果直接传递指针，则 Put 将写入指针变量的内存，而不是它所指向的内存。

amount

使 Put 向文件写入 amount 个连续变量——即从内存中 data 位置开始，向文件写入 ( amount * Sizeof(data) ) 字节的数据。如果省略 amount，默认为 1，意味着 Put 只写入单个变量。

返回值

Put() 返回 32 位 Long：成功时为 0；失败时为非零。"磁盘已满"被视为错误，返回代码 3。无法获得之前写入的"精确"数据量，实际上也不太有用。

说明

将缓冲区变量中的二进制数据写入以 Binary 或 Random 模式打开的文件。

Put 可以作为函数使用，成功时返回 0，失败时返回错误代码。

对于以 Random 模式打开的文件，要写入的数据字节大小必须与指定的记录大小匹配。

*注意：

• 如果将实际的 [w/z]string 变量传递给 Put，amount 参数应该被禁止，就像传递字符串时一样。不要使用。否则，它会被危险地用于乘以要写入文件的字符串长度，但可能会超出提供的 [w/z]string 缓冲区。

• 如果将解引用的 [w/z]string 指针传递给 Put，amount 参数不会被考虑，就像传递解引用的数值指针时一样。不要使用。但指向的缓冲区会被写入文件直到零元素（不包括终止元素），而不是遵循 amount 参数。

• 为了更精细的粒度，任何 [w/z]string 变量都可以通过提供第一个数值元素（索引的 [w/z]string 变量，或解引用的 [w/z]string 指针然后索引）和要处理的数值元素数量，安全地作为数值缓冲区传递给 Put。*

注意：

• 使用 Put # 自然专用于 Binary/Random 访问文件模式。

• 在 Output/Append 访问文件模式中也允许使用，但这从未经过良好测试，结果可能有所不同。