GFS_PIO_OPEN(3)

💖 GFS_PIO_OPEN(3) — the Gfarm manual, bestie edition 💖

okay so we're diving into Gfarm's very own file-opening girlie, gfs_pio_open. yes she's a libc-flavored queen, yes she lives in section 3 of the manual, and yes she's about to open a file for you in the Gfarm file system. let's get into it 🫶

✨ NAME ✨

gfs_pio_open — open a file in the Gfarm file system

🌸 SYNOPSIS 🌸

#include <gfarm/gfarm.h>

gfarm_error_t gfs_pio_open(const char * gfarm_url, int flags,
                           GFS_File * gfp);

🦋 DESCRIPTION 🦋

so gfs_pio_open() opens a file in the Gfarm file system — the one you point at with gfarm_url — and hands you back a GFS_File structure, dropped right at the address that gfp is pointing to. 💅

and what even is gfarm_url? it's either a plain old path name in the Gfarm file system, or a full Gfarm URL shaped like gfarm://metaserver:port/path/name. both are valid, she's flexible like that. ✨

now, flags. you build these by bitwise-inclusive-OR-ing the list below together. and listen — exactly one of the first three values should be specified. not two. not zero. one. the vibe check is strict on this. 🙈

• GFARM_FILE_RDONLY — open for reading only 📖
• GFARM_FILE_WRONLY — open for writing only ✍️
• GFARM_FILE_RDWR — open for reading and writing, main character energy 👑
• GFARM_FILE_TRUNC — if the file already exists and it's a regular file, it gets truncated to length 0, but only if the open mode actually allows writing
• GFARM_FILE_APPEND — the file is opened in append mode
• GFARM_FILE_UNBUFFERED — the file is accessed without buffering

💜 RETURN VALUES 💜

here's the whole roster of what she can hand back to you. no skipping, we're listing all of them because every single one matters: 🎀

• GFARM_ERR_NO_ERROR — the function terminated successfully 🎉
• GFARM_ERR_IS_A_DIRECTORY — gfarm_url refers to a directory
• 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_NO_SUCH_OBJECT — a component used as a directory in gfarm_url does not exist
• GFARM_ERR_NOT_A_DIRECTORY — a component used as a directory in gfarm_url is not, in fact, a directory
• 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 authentication to the metadata server fails
• GFARM_ERR_NO_MEMORY — insufficient memory was available
• GFARM_ERR_INVALID_ARGUMENT — flags is not valid
• 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
• GFARM_ERR_TOO_MANY_OPEN_FILES — the process opens too many files
• GFARM_ERR_TOO_MANY_OPEN_FILES_IN_SYSTEM — the system limit on the total number of open files has been reached
• GFARM_ERR_NETWORK_IS_UNREACHABLE — network is unreachable
• GFARM_ERR_OPERATION_TIMED_OUT — connection 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
• Others — an error except the above occurred. the reason is shown by gfarm_error_string(3)

🌈 SEE ALSO 🌈

go read these too, they're all in the family, iykyk:

• 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's from Gfarm, dated 8 Aug 2020. periodt. 🌸✨