GFS_PIO_CREATE(3)

✨ GFS_PIO_CREATE ✨

okay bestie, welcome to the Gfarm girlies' corner of the man pages 💅 today we're talking about gfs_pio_create, and yes she's from the Gfarm manual, section 3, and yes she EATS. let's get into it 🫶

🌸 NAME 🌸

gfs_pio_create — bestie makes a brand new file in the Gfarm file system. new file, who dis 💖

🦋 SYNOPSIS 🦋

#include <gfarm/gfarm.h>

gfarm_error_t gfs_pio_create(const char * gfarm_url, int flags,
                             gfarm_mode_t mode, GFS_File * gfp);

✨ DESCRIPTION ✨

so gfs_pio_create() literally creates a new file in the Gfarm file system. the name is the string that gfarm_url points to, and the access mode is mode, and she hands you back a GFS_File structure at the address gfp points to. iconic behavior tbh.

mode is the file permissions the file gets created with — and ngl it gets modified by the process's umask, so don't come crying if your bits aren't what you expected, that's just how the umask works 🎀

now, the flags argument? same meaning as the second argument of gfs_pio_open(), including the part where you must specify exactly one of GFARM_FILE_RDONLY, GFARM_FILE_WRONLY, and GFARM_FILE_RDWR. exactly one, bestie. not zero, not two. we don't do that here 🫶

on top of that, you can also pass GFARM_FILE_EXCLUSIVE. with that flag, gfs_pio_create() will fail if the file already exists. no overwriting, no drama, she said no 💀

⚠️ and listen, important: GFARM_FILE_TRUNC must be explicitly specified in the flags argument if you actually want it. she does NOT do it for you. not me assuming it would 😭

🌈 RETURN VALUES 🌈

here's the full tea on what she can hand back to you, no skips, no summaries, we're doing all of them 💜

• GFARM_ERR_NO_ERROR — the function terminated successfully. slay! she did it! 🎉
• GFARM_ERR_IS_A_DIRECTORY — gfarm_url refers to a directory. babe that's a folder, not a file 🙈
• GFARM_ERR_IS_A_SYMBOLIC_LINK — gfarm_url refers to a symbolic link.
• GFARM_ERR_OPERATION_NOT_PERMITTED — gfarm_url refers to not a regular file.
• GFARM_ERR_NOT_A_DIRECTORY — a component used as a directory in gfarm_url is not, in fact, a directory. plot twist 😭
• GFARM_ERR_PERMISSION_DENIED — the requested access to the file is not allowed, or one of the directories in gfarm_url didn't allow search (execute) permission, or the file didn't exist yet and write access to the parent directory is not allowed. Or, the authentication to the metadata server fails. yes that's a lot of ors, she's a multitasker 💅
• GFARM_ERR_NO_MEMORY — insufficient memory was available. she's running on fumes bestie 💀
• GFARM_ERR_INVALID_ARGUMENT — flags is not valid. girl. what did you pass. 😭
• GFARM_ERR_GFARM_URL_HOST_IS_MISSING — gfarm_url does not include a metadata server.
• GFARM_ERR_GFARM_URL_PORT_IS_MISSING — gfarm_url does not include a port number of the metadata server.
• GFARM_ERR_UNKNOWN_HOST — the metadata server cannot be resolved. she's lost in the sauce 🧚
• GFARM_ERR_TOO_MANY_OPEN_FILES — the process opens too many files. bestie, close some of them, fr fr.
• GFARM_ERR_TOO_MANY_OPEN_FILES_IN_SYSTEM — the system limit on the total number of open files has been reached. that one's not even your fault, the whole system said no 🔥
• GFARM_ERR_NETWORK_IS_UNREACHABLE — network is unrechable.
• GFARM_ERR_OPERATION_TIMED_OUT — connetion timeout occurs.
• GFARM_ERR_PROTOCOL — protocol error occurs.
• GFARM_ERR_BROKEN_PIPE — connection to the metadata server is broken. 💔
• GFARM_ERR_PROTOCOL_NOT_SUPPORTED — specified authentication protocol is not supported.
• GFARM_ERR_AUTHENTICATION — user authentication failed when connecting to the metadata server. she did not recognize you 😔
• GFARM_ERR_ALREADY_EXISTS — gfarm_url already exists and GFARM_FILE_EXCLUSIVE was used. told you, exclusive means exclusive 👑
• Others — an error except the above occurred. the reason is shown by gfarm_error_string(3). when in doubt, go ask her 🫶

🎀 SEE ALSO 🎀

the whole girl squad, all linked, all iconic:

gfs_pio_close(3), gfs_pio_create(3), gfs_pio_eof(3), gfs_pio_error(3), gfs_pio_flush(3), gfs_pio_getc(3), gfs_pio_getline(3), gfs_pio_open(3), gfs_pio_putc(3), gfs_pio_putline(3), gfs_pio_puts(3), gfs_pio_read(3), gfs_pio_seek(3), gfs_pio_ungetc(3), gfs_pio_write(3)

and that's the whole page bestie!! ✨💖

this one came straight from the Gfarm crew, dated 3 Sep 2015 — yeah she's a classic, an OG, and she still serves 💅🏽 mwah, go create some files responsibly, ily, bye 🦋🌸