Missing F_* constants in fcntl module on macOS

[ronaldoussoren]

Feature or enhancement

Proposal:

There's a fairly large number of F_* macros that are present in sys/fcntl.h on macOS, but are not exposed in fcntlmodule.c:

• F_SETLKWTIMEOUT
• F_FLUSH_DATA
• F_CHKCLEAN
• F_PREALLOCATE
• F_SETSIZE (No-op)
• F_RDADVISE
• F_RDAHEAD
• F_LOG2PHYS
• F_PATHPKG_CHECK (found no public use other than XNU kernel, can't get test to work)
• F_FREEZE_FS
• F_THAW_FS
• F_GLOBAL_NOCACHE
• F_ADDSIGS
• F_ADDFILESIGS
• F_NODIRECT
• F_GETPROTECTIONCLASS
• F_SETPROTECTIONCLASS
• F_LOG2PHYS_EXT
• F_GETLKPID
• F_SETBACKINGSTORE
• F_GETPATH_MTMINFO
• F_GETCODEDIR
• F_SETNOSIGPIPE
• F_GETNOSIGPIPE
• F_TRANSCODEKEY
• F_SINGLE_WRITER
• F_GETPROTECTIONLEVEL
• F_FINDSIGS
• F_ADDFILESIGS_FOR_DYLD_SIM
• F_BARRIERFSYNC
• F_OFD_SETLKWTIMEOUT
• F_ADDFILESIGS_RETURN
• F_CHECK_LV
• F_PUNCHHOLE
• F_TRIM_ACTIVE_FILE
• F_SPECULATIVE_READ
• F_GETPATH_NOFIRMLINK
• F_ADDFILESIGS_INFO
• F_ADDFILESUPPL
• F_GETSIGSINFO
• F_TRANSFEREXTENTS
• F_ATTRIBUTION_TAG
• F_ALLOCATECONTIG
• F_ALLOCATEALL
• F_ALLOCATEPERSIST
• F_PEOFPOSMODE
• F_VOLPOSMODE
• F_CREATE_TAG
• F_DELETE_TAG
• F_QUERY_TAG

Fixing this issue requires more than just adding definitions for the macros above, but also needs new tests to check that these settings are actually usable.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-113092: Add fcntl.preallocate #139795
• gh-113092: Support F_PREALLOCATE in fcntl #139864

[serhiy-storchaka]

#114322 includes some names from this long list which happens to exist on other platforms.

[ronaldoussoren]

I thing I noticed while working on this: at least one of the constants is defined as requiring a buffer of PATH_MAX bytes to read the value (IIRC F_GETPATH). The buffer we're using is only 1K long.

[serhiy-storchaka]

Some of constants require an access to a specific C struct. I am currently working on adding Python interface to such structs for Linux and FreeBSD, and it may results in some convenient helper C API. But this requires some preparatory steps (#114388, #114392, and some more).

It can help to do similar on macOS.

[aisk]

I have tried adding the F_ATTRIBUTION_TAG operation, which accepts a struct pointer. This allows setting flags on the struct with values F_CREATE_TAG, F_DELETE_TAG, or F_QUERY_TAG.

I think this operation is used to set or retrieve an attribute tag on a file, but all operations failed with ENOTSUP.

There is a simple C program to call them, using it on a Intel mac with Sonoma 14.2 with sudo leads to the same result, as does F_QUERY_TAG:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <fcntl.h>
#include <unistd.h>
#include <errno.h>
#include <sys/types.h>

int main(int argc, char *argv[]) {
    if (argc != 3) {
        fprintf(stderr, "Usage: %s <file> <tag_name>\n", argv[0]);
        return 1;
    }

    const char *path = argv[1];
    const char *tag_name = argv[2];

    int fd = open(path, O_RDWR | O_CREAT, 0644);
    if (fd < 0) {
        perror("open");
        return 1;
    }

    fattributiontag_t tag;
    memset(&tag, 0, sizeof(tag));
    tag.ft_flags = F_CREATE_TAG;
    strncpy(tag.ft_attribution_name, tag_name, ATTRIBUTION_NAME_MAX - 1);

    if (fcntl(fd, F_ATTRIBUTION_TAG, &tag) == -1) {
        perror("fcntl(F_ATTRIBUTION_TAG)");
        close(fd);
        return 1;
    }

    printf("Successfully set attribution tag:\n");
    printf("  Name: %s\n", tag.ft_attribution_name);
    printf("  Hash: 0x%016llx\n", tag.ft_hash);

    close(fd);
    return 0;
}

I searched for F_ATTRIBUTION_TAG and found it only in macOS's fcntl.h, suggesting it may be a private or deprecated constant.

Should we avoid adding them?