---
name: "gfs_pio_create"
section: "3"
platform: "linux"
package: "libgfarm-dev"
version: "2.7.20+dfsg-1.2+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/gfs_pio_create"
---

# gfs\_pio\_create(3)

create a file in the Gfarm file system

## NAME

gfs\_pio\_create - create a file in the Gfarm file system

## 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

**gfs\_pio\_create()** creates a new file in the Gfarm file system whose name is the string pointed to by *gfarm\_url* with the access mode *mode*, and returns a *GFS\_File* structure to the address pointed to by *gfp*. *Mode* specifies the file permissions to be created, and is modified by the process's *umask*.

The *flags* argument has the same meaning as the second argument of **gfs\_pio\_open()**, including the point such that exactly one of *GFARM\_FILE\_RDONLY*, *GFARM\_FILE\_WRONLY*, and *GFARM\_FILE\_RDWR* should be specified. In addition, it is possible to specify *GFARM\_FILE\_EXCLUSIVE*. With this flag, **gfs\_pio\_create()** will fail when the file already exists.

Note that *GFARM\_FILE\_TRUNC* must be explicitly specified by the *flags* argument if needed.

## RETURN VALUES

**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\_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* did not allow search (execute) permission, or the file did not exist yet and write access to the parent directory is not allowed. 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 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.

**GFARM\_ERR\_ALREADY\_EXISTS**

*gfarm\_url* already exists and GFARM\_FILE\_EXCLUSIVE was used.

Others

An error except the above occurred. The reason is shown by **gfarm\_error\_string**(3).

## SEE ALSO

[**gfs\_pio\_close**(3)](/gfs_pio_close/3.md), [**gfs\_pio\_create**(3)](/gfs_pio_create/3.md), [**gfs\_pio\_eof**(3)](/gfs_pio_eof/3.md), [**gfs\_pio\_error**(3)](/gfs_pio_error/3.md), [**gfs\_pio\_flush**(3)](/gfs_pio_flush/3.md), [**gfs\_pio\_getc**(3)](/gfs_pio_getc/3.md), [**gfs\_pio\_getline**(3)](/gfs_pio_getline/3.md), [**gfs\_pio\_open**(3)](/gfs_pio_open/3.md), [**gfs\_pio\_putc**(3)](/gfs_pio_putc/3.md), [**gfs\_pio\_putline**(3)](/gfs_pio_putline/3.md), [**gfs\_pio\_puts**(3)](/gfs_pio_puts/3.md), [**gfs\_pio\_read**(3)](/gfs_pio_read/3.md), [**gfs\_pio\_seek**(3)](/gfs_pio_seek/3.md), [**gfs\_pio\_ungetc**(3)](/gfs_pio_ungetc/3.md), [**gfs\_pio\_write**(3)](/gfs_pio_write/3.md)