NAME

rf_create − create a realtime file

SYNOPSIS

#include <rtfiles.h>

int rf_create(path, mode, reqattr, reqwhich, actattr, actwhich)
const char ∗path;
mode_t mode;
int reqwhich, ∗actwhich;
struct rf_attrbuf ∗reqattr, ∗actattr;

DESCRIPTION

The rf_create function creates a new file with realtime attributes.  It can also be used to rewrite an existing file.  The path and mode arguments are the same as creat(2). 

The reqwhich argument specifies which of the attributes shall be set.  This is done using the logical OR of the following flags:

ATB_ALLOC
Preallocation size.

ATB_ALLOCFLAGS
Preallocation flags.

ATB_CACHEFLAGS
Caching flags.

ATB_DIOFLAGS
Direct I/O flags.

ATB_DIOSIZE
Direct I/O transfer size.

ATB_ALL
All of the above flags.

The reqattr and actattr arguments point to structures of type rf_attrbuf. 

The requested attributes of the file are specified in the rf_attrbuf structure specified by the reqattr argument. 

The resulting attributes of the file are stored in actattr upon successful completion of the function.  See rf_getattr. 

The rf_attrbuf structure is declared in the <rtfiles.h> header file.  The structure has the following members:

off_t    atb_alloc;
int      atb_allocflags;
int      atb_cacheflags;
int      atb_dioflags;
unsigned atb_diosize;

The field atb_alloc contains the preallocation size, in bytes.  Upon return, it contains the actual file extension size. 

atb_allocflags contains flags which pertain to file space allocation:

ATB_SEQ
Allocate file space in a manner consistent with sequential access.

ATB_ADVSEQ
Allocate file space optimized for sequential access.

atb_cacheflags contains flags that pertain to the type of caching desired:

ATB_CACHENOREUSE
Recently accessed blocks are not likely to be accessed in the near future.

ATB_CACHERANDOM
Blocks will be accessed randomly.

ATB_CACHESEQUENTIAL
Blocks will be access sequentially.

atb_dioflags contains flags for direct I/O:

ATB_DIOENABLE
Enable direct I/O for subsequent read and write operations. 

The field atb_diosize contains the direct I/O transfer size in bytes.  This should not be specified on CX systems since a single direct I/O transfer size is not required. 

The actwhich argument points to a flags word.  This uses the same flags as reqwhich.  Upon successful completion, actwhich will indicate which actual attributes were different from the requested attributes.  In other words, if a flag is set in actwhich then the corresponding field of the actattr structure does not match the corresponding field of the reqattr structure.  Upon unsuccessful completion, actwhich will indicate all requested attributes that were found to be invalid or in conflict with other attributes. 

RETURN VALUE

Upon successful completion, the function opens the file for writing and returns a non-negative integer representing the file descriptor.  The file pointer is set to the beginning of the file.  (See creat(2)).  The resultant attributes will be stored in the rf_attrbuf pointed to by actattr.  The flags word actwhich will indicate which of the resultant attributes are different from the requested attributes. 

Upon unsuccessful completion, rf_create returns a value of -1 and sets errno to indicate an error.  The flags word pointed to by actwhich will indicate any attributes were in error. 

ERRORS

Under the following conditions, the function rf_create fails and sets errno to:

­[EACCES] Search permission is denied on a component of the path prefix, or the file exists and write permission is denied, or the file does not exist and write permission is denied for the parent directory of the file to be created, or the file exists and write permission is denied. 

­[EEXIST] The specified file already exists and is not a regular file. 

­[EFAULT] Path points outside of the allocated address space for the process. 

­[EINVAL] The rf_create function in not supported for the specified file or file system. 

­[EINVAL] One or more of the requested attributes was not valid or in conflict with an attribute specified on another open instance of this file.  Upon return, actwhich will indicate which parameters were found to be in error. 

­[EISDIR] The named file is an existing directory. 

­[EMFILE] Too many file descriptors are currently in use by this process. 

­[ENAMETOOLONG]
The length of the path string exceeds PATH_MAX, or a pathname component is longer than NAME_MAX. 

­[ENFILE] Too many files are currently open in the system. 

­[ENOENT] Either the path prefix does not exist or the path argument points to an empty string. 

­[ENOSPC] The directory or file system that would contain the new file cannot be extended. 

­[ENOTDIR] A component of the path prefix is not a directory. 

­[EROFS] The requested operation requires writing in a directory on a read-only file system. 

SEE ALSO

creat(2), open(2),
rf_setattr(3P4), rf_getattr(3P4).

NOTES

The attribute ATB_CACHENOREUSE is not supported on CX systems. 

A file in direct mode does not use the cache.  None of the cache flags may be set. 

WARNING

rf_create is based on IEEE Draft Standard P1003.4/D12.  This is an unapproved draft, subject to change.  Use of information contained in this unapproved draft is at your own risk.  This interface will change to reflect any changes made by future drafts of POSIX 1003.4. 

CX/UX Programmer’s Reference Manual