File Descriptor and I/O Control

`fcntl`

Supported functionality in SCML:

ignore_flags = O_RDONLY | O_WRONLY | O_RDWR | O_CREAT | O_EXCL | O_NOCTTY | O_TRUNC;
can_change_flags = O_APPEND | O_ASYNC | O_DIRECT | O_NOATIME | O_NONBLOCK;

// Duplicate a file descriptor
fcntl(fd, cmd = F_DUPFD | F_DUPFD_CLOEXEC, arg);

// Retrieve file descriptor flags (F_GETFD), file status flags (F_GETFL)
// or SIGIO/SIGURG owner process (F_GETOWN)
fcntl(fd, cmd = F_GETFD | F_GETFL | F_GETOWN);

// Set file descriptor flags
fcntl(fd, cmd = F_SETFD, arg = FD_CLOEXEC);

// Set file status flags
fcntl(fd, cmd = F_SETFL, arg = <ignore_flags> | <can_change_flags>);

// Manage record locks: test (F_GETLK), non-blocking set (F_SETLK), blocking set (F_SETLKW)
fcntl(fd, cmd = F_GETLK | F_SETLK | F_SETLKW, arg);

// Assign SIGIO/SIGURG owner process
fcntl(fd, cmd = F_SETOWN, arg);

// Add seals to the inode referred to
fcntl(fd, cmd = F_ADD_SEALS, arg = F_SEAL_SEAL | F_SEAL_SHRINK | F_SEAL_GROW | F_SEAL_WRITE | F_SEAL_FUTURE_WRITE);

// Get seals from the inode referred to
fcntl(fd, cmd = F_GET_SEALS);

Unsupported commands:

F_NOTIFY
F_OFD_SETLK, F_OFD_SETLKW and F_OFD_GETLK
F_GETOWN_EX and F_SETOWN_EX
F_GETSIG and F_SETSIG
F_SETLEASE and F_GETLEASE
F_SETPIPE_SZ and F_GETPIPE_SZ
F_GET_RW_HINT and F_SET_RW_HINT
F_GET_FILE_RW_HINT and F_SET_FILE_RW_HINT

For more information, see the man page.

`pipe` and `pipe2`

Supported functionality in SCML:

// Create pipe
pipe(pipefd);

// Create pipe with enhanced behavior control
pipe2(pipefd, flags = O_CLOEXEC);

Silently-ignored flags:

O_DIRECT
O_NONBLOCK

For more information, see the man page.

`eventfd` and `eventfd2`

Supported functionality in SCML:

// Create event notification descriptor
eventfd(initval);

// Create event notification descriptor with enhanced behavior control
eventfd2(initval, flags = EFD_CLOEXEC);

Silently-ignored flags:

EFD_NONBLOCK
EFD_SEMAPHORE

For more information, see the man page.

`memfd_create`

Supported functionality in SCML:

// Create an anonymous file and return a file descriptor that refers to it
memfd_create(name, flags = MFD_CLOEXEC | MFD_ALLOW_SEALING);

Silently-ignored flags:

MFD_HUGETLB

Unsupported flags:

MFD_HUGE_64KB
MFD_HUGE_512KB
MFD_HUGE_1MB
MFD_HUGE_2MB
MFD_HUGE_8MB
MFD_HUGE_16MB
MFD_HUGE_32MB
MFD_HUGE_256MB
MFD_HUGE_512MB
MFD_HUGE_1GB
MFD_HUGE_2GB
MFD_HUGE_16GB

For more information, see the man page.

`fadvise64`

Supported functionality in SCML:

// Announce an intention to access file data in a specific pattern in the future
fadvise64(fd, offset, len, advice = 0);

Silently-ignored flags:

POSIX_FADV_NORMAL
POSIX_FADV_RANDOM
POSIX_FADV_SEQUENTIAL
POSIX_FADV_WILLNEED
POSIX_FADV_DONTNEED
POSIX_FADV_NOREUSE

For more information, see the man page.

`epoll_ctl`

Supported functionality in SCML:

struct epoll_event = {
    events = EPOLLIN | EPOLLOUT | EPOLLRDHUP | EPOLLPRI | EPOLLERR | EPOLLHUP |
             EPOLLET | EPOLLONESHOT,
    ..
};

// Add, modify, or delete entries in the interest list of an epoll file descriptor
epoll_ctl(
    epfd,
    op = EPOLL_CTL_ADD | EPOLL_CTL_MOD | EPOLL_CTL_DEL,
    fd, event = <epoll_event>
);

Unsupported flags in events:

EPOLLEXCLUSIVE
EPOLLWAKEUP

For more information, see the man page.

`poll` and `ppoll`

Supported functionality in SCML:

struct pollfd = {
    events = POLLIN | POLLPRI | POLLOUT | POLLRDHUP | POLLERR |
             POLLHUP | POLLNVAL | POLLRDNORM,
    ..
};

// Wait for I/O event on a set of file descriptors
poll(fds = [ <pollfd> ], nfds, timeout);

// Wait for I/O event on a set of file descriptors with specified signals temporarily blocked
ppoll(fds = [ <pollfd> ], nfds, timeout, sigset, sigset_size);

Unsupported events:

POLLRDBAND
POLLWRNORM
POLLWRBAND

For more information, see the man page.

`ioctl`

Supported functionality in SCML:

tty_ops = TCGETS | TCSETS | TCSETSW | TCSETSF | TIOCGWINSZ | TIOCSWINSZ |
          TIOCGPTN | FIONREAD | KDFONTOP | KDSETMODE | KDGETMODE |
          KDSKBMODE | KDGKBMODE;
term_ops = TIOCGPGRP | TIOCSPGRP | TIOCSCTTY | TIOCNOTTY | TIOCGSID;
pty_master_ops = TIOCSPTLCK | TIOCGPTLCK | TIOCGPTPEER | TIOCPKT | TIOCGPKT;

// Control file descriptor flags and I/O modes
ioctl(fd, op = FIONCLEX | FIOCLEX | FIONBIO | FIOASYNC, ..);

// Control terminal devices
ioctl(fd, op = <pty_master_ops> | <tty_ops> | <term_ops>, ..);

// Control framebuffer display
ioctl(
    fd,
    op = FBIOGET_VSCREENINFO | FBIOPUT_VSCREENINFO | FBIOGET_FSCREENINFO |
         FBIOGETCMAP | FBIOPUTCMAP | FBIOPAN_DISPLAY | FBIOBLANK,
    ..
);

// Control Event devices (evdev)
ioctl(
    fd,
    op = EVIOCGVERSION | EVIOCGID | EVIOCGNAME | EVIOCGPHYS | EVIOCGUNIQ |
         EVIOCGKEY | EVIOCGLED | EVIOCGSW | EVIOCSCLOCKID | EVIOCGBIT,
    ..
);

// Control Trust Domain Extensions (TDX) guest devices
ioctl(fd, op = TDX_CMD_GET_REPORT0, ..);

For more information, see the man page.

`ioprio_set` and `ioprio_get`

Supported functionality in SCML:

// Set the I/O priority for a single thread
ioprio_set(which = IOPRIO_WHO_PROCESS, who, ioprio);

// Get the I/O priority for a single thread
ioprio_get(which = IOPRIO_WHO_PROCESS, who);

Unsupported selectors:

IOPRIO_WHO_PGRP
IOPRIO_WHO_USER

For more information, see the man page.

Keyboard shortcuts

The Asterinas Book