跳转至
项目
版本
全文检索

fcntl

fcntl 提供文件控制相关功能，包括文件打开与创建、文件描述符操作、文件锁管理以及文件数据访问建议。

头文件清单

#include "open_source/musl/include/fcntl.h"

接口清单

接口名称 功能简述
creat 创建一个文件
fcntl 文件描述词操作
open 打开文件
openat 相对于目录文件描述符打开文件
posix_fadvise 文件数据访问建议
posix_fallocate 文件空间预分配

Functions

creat 

int creat(const char *, mode_t)

头文件清单

#include "open_source/musl/include/fcntl.h"

功能说明

  • 创建一个新文件，若文件已存在则将其长度截断为0
  • 等效于以O_CREAT|O_WRONLY|O_TRUNC标志调用open函数
  • 通过mode参数指定新创建文件的访问权限

入参

名称 参数类型 详细说明 约束取值范围
pathname const char * 待创建文件的路径名 不为NULL
mode mode_t 新创建文件的访问权限 S_IRUSR(0400) / S_IWUSR(0200) / S_IXUSR(0100) / S_IRGRP(0040) / S_IWGRP(0020) / S_IXGRP(0010) / S_IROTH(0004) / S_IWOTH(0002) / S_IXOTH(0001) 等权限宏按位或组合

返回值

返回值 文字含义 触发场景
非负整数 文件描述符 文件创建成功
-1 操作失败 文件创建失败，errno被设置

fcntl 

int fcntl(int, int, ...)

头文件清单

#include "open_source/musl/include/fcntl.h"

功能说明

  • 对已打开的文件描述符执行各种控制操作
  • 支持复制文件描述符、获取/设置文件描述符标志、获取/设置文件状态标志、管理文件锁等操作
  • 第三个可选参数的类型和含义取决于cmd命令

入参

名称 参数类型 详细说明 约束取值范围
fd int 文件描述符 非负整数
cmd int 控制命令 F_DUPFD(0) / F_GETFD(1) / F_SETFD(2) / F_GETFL(3) / F_SETFL(4) / F_GETLK(5) / F_SETLK(6) / F_SETLKW(7) / F_SETOWN(8) / F_GETOWN(9) / F_DUPFD_CLOEXEC(1030)
... 可变参数 可选第三参数，类型取决于cmd：F_DUPFD/F_DUPFD_CLOEXEC为int，F_SETFD/F_SETFL为int，F_SETOWN为int，F_GETLK/F_SETLK/F_SETLKW为struct flock * -

返回值

返回值 文字含义 触发场景
非负整数 新文件描述符 F_DUPFD/F_DUPFD_CLOEXEC复制文件描述符成功
标志值 文件描述符标志或文件状态标志 F_GETFD/F_GETFL/F_GETOWN获取标志成功
0 操作成功 F_SETFD/F_SETFL/F_SETLK/F_SETLKW/F_SETOWN等设置操作成功
-1 操作失败 操作失败，errno被设置

open 

int open(const char *, int, ...)

头文件清单

#include "open_source/musl/include/fcntl.h"

功能说明

  • 打开一个已存在的文件或创建并打开一个新文件
  • 通过oflag参数指定文件的打开方式及附加标志
  • 当oflag包含O_CREAT时，第三个参数mode用于指定新创建文件的访问权限

入参

名称 参数类型 详细说明 约束取值范围
pathname const char * 待打开文件的路径名 不为NULL
oflag int 文件打开标志 O_RDONLY(00) / O_WRONLY(01) / O_RDWR(02) / O_CREAT(0100) / O_EXCL(0200) / O_NOCTTY(0400) / O_TRUNC(01000) / O_APPEND(02000) / O_NONBLOCK(04000) / O_DSYNC(010000) / O_SYNC(04010000) / O_RSYNC(04010000) / O_DIRECTORY(0200000) / O_NOFOLLOW(0400000) / O_CLOEXEC(02000000)
... 可变参数 mode：新创建文件的访问权限，仅当oflag包含O_CREAT时有效 mode_t

返回值

返回值 文字含义 触发场景
非负整数 文件描述符 文件打开成功
-1 操作失败 文件打开失败，errno被设置

openat 

int openat(int, const char *, int, ...)

头文件清单

#include "open_source/musl/include/fcntl.h"

功能说明

  • 相对于目录文件描述符打开文件
  • 当dirfd为AT_FDCWD时，pathname相对于当前工作目录
  • 支持与open相同的oflag标志和mode权限参数

入参

名称 参数类型 详细说明 约束取值范围
dirfd int 目录文件描述符 AT_FDCWD(-100) 或有效的目录文件描述符
pathname const char * 待打开文件的路径名 不为NULL
oflag int 文件打开标志 O_RDONLY(00) / O_WRONLY(01) / O_RDWR(02) / O_CREAT(0100) / O_EXCL(0200) / O_NOCTTY(0400) / O_TRUNC(01000) / O_APPEND(02000) / O_NONBLOCK(04000) / O_DSYNC(010000) / O_SYNC(04010000) / O_RSYNC(04010000) / O_DIRECTORY(0200000) / O_NOFOLLOW(0400000) / O_CLOEXEC(02000000)
... 可变参数 mode：新创建文件的访问权限，仅当oflag包含O_CREAT时有效 mode_t

返回值

返回值 文字含义 触发场景
非负整数 文件描述符 文件打开成功
-1 操作失败 文件打开失败，errno被设置

posix_fadvise 

int posix_fadvise(int, off_t, off_t, int)

头文件清单

#include "open_source/musl/include/fcntl.h"

功能说明

  • 向内核提供文件数据访问模式的建议
  • 允许应用声明对文件指定区域的预期访问模式以优化I/O调度
  • 建议不影响程序正确性，仅影响性能

入参

名称 参数类型 详细说明 约束取值范围
fd int 文件描述符 非负整数
offset off_t 建议区域的起始偏移量 ≥ 0
len off_t 建议区域的长度 ≥ 0，0表示从offset到文件末尾
advice int 访问建议 POSIX_FADV_NORMAL(0) / POSIX_FADV_RANDOM(1) / POSIX_FADV_SEQUENTIAL(2) / POSIX_FADV_WILLNEED(3) / POSIX_FADV_DONTNEED(4) / POSIX_FADV_NOREUSE(5)

返回值

返回值 文字含义 触发场景
0 执行成功 操作成功
非0 错误号 参数无效或操作失败

posix_fallocate 

int posix_fallocate(int, off_t, off_t)

头文件清单

#include "open_source/musl/include/fcntl.h"

功能说明

  • 为文件指定区域预分配磁盘空间
  • 确保文件的指定范围有足够的磁盘空间，避免后续写入时磁盘空间不足
  • 若文件当前大小不足则扩展文件至offset+len

入参

名称 参数类型 详细说明 约束取值范围
fd int 文件描述符 非负整数
offset off_t 预分配区域的起始偏移量 ≥ 0
len off_t 预分配区域的长度 > 0

返回值

返回值 文字含义 触发场景
0 执行成功 空间预分配成功
非0 错误号 参数无效或磁盘空间不足

Structures

struct flock 

struct flock {
    short l_type;
    short l_whence;
    off_t l_start;
    off_t l_len;
    pid_t l_pid;
};

成员说明

成员名称 数据类型 描述
l_type short 锁类型，取值为F_RDLCK、F_WRLCK或F_UNLCK
l_whence short 锁起始位置的偏移基准，取值为SEEK_SET、SEEK_CUR或SEEK_END
l_start off_t 锁起始位置的偏移量
l_len off_t 锁的长度，0表示锁到文件末尾
l_pid pid_t 持有锁的进程ID（仅F_GETLK时由内核填充）

Macros

O_RDONLY 

#define O_RDONLY  00

O_WRONLY 

#define O_WRONLY  01

O_RDWR 

#define O_RDWR    02

O_CREAT 

#define O_CREAT        0100

O_EXCL 

#define O_EXCL         0200

O_NOCTTY 

#define O_NOCTTY       0400

O_TRUNC 

#define O_TRUNC       01000

O_APPEND 

#define O_APPEND      02000

O_NONBLOCK 

#define O_NONBLOCK    04000

O_DSYNC 

#define O_DSYNC      010000

O_SYNC 

#define O_SYNC     04010000

O_RSYNC 

#define O_RSYNC    04010000

O_DIRECTORY 

#define O_DIRECTORY 0200000

O_NOFOLLOW 

#define O_NOFOLLOW  0400000

O_CLOEXEC 

#define O_CLOEXEC  02000000

O_ASYNC 

#define O_ASYNC      020000

O_NDELAY 

#define O_NDELAY O_NONBLOCK

F_DUPFD 

#define F_DUPFD  0

F_GETFD 

#define F_GETFD  1

F_SETFD 

#define F_SETFD  2

F_GETFL 

#define F_GETFL  3

F_SETFL 

#define F_SETFL  4

F_GETLK 

#define F_GETLK  5

F_SETLK 

#define F_SETLK  6

F_SETLKW 

#define F_SETLKW 7

F_SETOWN 

#define F_SETOWN 8

F_GETOWN 

#define F_GETOWN 9

F_DUPFD_CLOEXEC 

#define F_DUPFD_CLOEXEC 1030

F_RDLCK 

#define F_RDLCK 0

F_WRLCK 

#define F_WRLCK 1

F_UNLCK 

#define F_UNLCK 2

FD_CLOEXEC 

#define FD_CLOEXEC 1

AT_FDCWD 

#define AT_FDCWD (-100)

SEEK_SET 

#define SEEK_SET 0

SEEK_CUR 

#define SEEK_CUR 1

SEEK_END 

#define SEEK_END 2

S_ISUID 

#define S_ISUID 04000

S_ISGID 

#define S_ISGID 02000

S_ISVTX 

#define S_ISVTX 01000

S_IRUSR 

#define S_IRUSR 0400

S_IWUSR 

#define S_IWUSR 0200

S_IXUSR 

#define S_IXUSR 0100

S_IRWXU 

#define S_IRWXU 0700

S_IRGRP 

#define S_IRGRP 0040

S_IWGRP 

#define S_IWGRP 0020

S_IXGRP 

#define S_IXGRP 0010

S_IRWXG 

#define S_IRWXG 0070

S_IROTH 

#define S_IROTH 0004

S_IWOTH 

#define S_IWOTH 0002

S_IXOTH 

#define S_IXOTH 0001

S_IRWXO 

#define S_IRWXO 0007

POSIX_FADV_NORMAL 

#define POSIX_FADV_NORMAL     0

POSIX_FADV_RANDOM 

#define POSIX_FADV_RANDOM     1

POSIX_FADV_SEQUENTIAL 

#define POSIX_FADV_SEQUENTIAL 2

POSIX_FADV_WILLNEED 

#define POSIX_FADV_WILLNEED   3

POSIX_FADV_DONTNEED 

#define POSIX_FADV_DONTNEED   4

POSIX_FADV_NOREUSE 

#define POSIX_FADV_NOREUSE    5