Filesystem

mm_fsync

#include <mmsysio.h>
int mm_fsync(int fd)

synchronize changes to a file

Parameters:
  • fd (int) – file description to synchronize

Description

This requests that all data for the open file descriptor named by fd is to be transferred to the storage device associated with the file described by fd. The mm_fsync() function does not return until the system has completed that action or until an error is detected.

Return

0 in case of success, -1 otherwise with error state set accordingly.

mm_seek

#include <mmsysio.h>
mm_off_t mm_seek(int fd, mm_off_t offset, int whence)

change file offset

Parameters:
  • fd (int) – file descriptor
  • offset (mm_off_t) – delta
  • whence (int) – how the offset affect the file offset

Description

This function sets the file offset for the open file description associated with the file descriptor fd, as follows depending on the value in whence

SEEK_SET
the file offset shall be set to offset bytes.
SEEK_CUR
the file offset shall be set to its current location plus offset.
SEEK_END
the file offset shall be set to the size of the file plus offset.

Return

in case of success, the resulting offset location as measured in bytes from the beginning of the file. Otherwise -1 with error state set accordingly.

mm_ftruncate

#include <mmsysio.h>
int mm_ftruncate(int fd, mm_off_t length)

truncate/resize a file to a specified length

Parameters:
  • fd (int) – file descriptor of the file to resize
  • length (mm_off_t) – new length of the file

Description

If fd refers to a regular file, mm_ftruncate() cause the size of the file to be truncated to length. If the size of the file previously exceeded length, the extra data shall no longer be available to reads on the file. If the file previously was smaller than this size, mm_ftruncate() increases the size of the file. If the file size is increased, the extended area will appear as if it were zero-filled. The value of the seek pointer shall not be modified by a call to mm_ftruncate().

Return

0 in case of success, -1 otherwise with error state set accordingly.

mm_mkdir

#include <mmsysio.h>
int mm_mkdir(const char* path, int mode, int flags)

creates a directory

Parameters:
  • path (const char*) – path of the directory to create
  • mode (int) – permission to use for directory creation
  • flags (int) – creation flags

Description

The mm_mkdir() function creates a new directory with name path. The file permission bits of the new directory shall be initialized from mode. These file permission bits of the mode argument are modified by the process’ file creation mask.

The function will fail if the parent directory does not exist unless flags contains MM_RECURSIVE which is this case, the function will try to recursively create the missing parent directories (using the file permission).

Return

0 in case of success, -1 otherwise with error state set accordingly.

mm_open

#include <mmsysio.h>
int mm_open(const char* path, int oflag, int mode)

Open file

Parameters:
  • path (const char*) – path to file to open
  • oflag (int) – control flags how to open the file
  • mode (int) – access permission bits is file is created

Description

This function creates an open file description that refers to a file and a file descriptor that refers to that open file description. The file descriptor is used by other I/O functions to refer to that file. The path argument points to a pathname naming the file.

The file status flags and file access modes of the open file description are set according to the value of oflag, which is constructed by a bitwise-inclusive OR of flags from the following list. It must specify exactly one of the first 3 values.

O_RDONLY
Open for reading only.
O_WRONLY
Open for writing only.
O_RDWR
Open for reading and writing. The result is undefined if this flag is applied to a FIFO.

Any combination of the following may be used

O_APPEND
If set, the file offset shall be set to the end of the file prior to each write.
O_CREAT
If the file exists, this flag has no effect except as noted under O_EXCL below. Otherwise, the file is created as a regular file; the user ID of the file shall be set to the effective user ID of the process; the group ID of the file shall be set to the group ID of the file’s parent directory or to the effective group ID of the process; and the access permission bits of the file mode are set by the mode argument modified by a bitwise AND with the umask of the process. This mode argument does not affect whether the file is open for reading, writing, or for both.
O_TRUNC
If the file exists and is a regular file, and the file is successfully opened O_RDWR or O_WRONLY, its length is truncated to 0, and the mode and owner are unchanged. The result of using O_TRUNC without either O_RDWR or O_WRONLY is undefined.
O_EXCL
If O_CREAT and O_EXCL are set, mm_open() fails if the file exists. The check for the existence of the file and the creation of the file if it does not exist is atomic with respect to other threads executing mm_open() naming the same filename in the same directory with O_EXCL and O_CREAT set.

Return

a non-negative integer representing the file descriptor in case of success. Otherwise -1 is returned with error state set accordingly.

mm_rename

#include <mmsysio.h>
int mm_rename(const char * oldpath, const char * newpath)

rename a file

Parameters:
  • oldpath (const char *) – old pathname of the file
  • newpath (const char *) – new pathname of the file

Description

The mm_rename() function changes the name of a file. oldpath is the path of the file to be renamed, and newpath is the new pathname of the file.

If newpath corresponds to the path of an existing file/directory, then it is removed and oldpath is renamed to newpath. Therefore, write access permission is required for both the directory containing oldpath and the directory containing newpath. Note that, in case newpath corresponds to the path of an existing directory, this directory is required to be empty.

If either oldpath or newpath is a path of a symbolic link, mm_rename() operates on the symbolic link itself.

If oldpath and newpath are identical paths mm_rename() returns successfully and performs no other action.

mm_rename() will non-trivially fail if:
  • Either oldpath or newpath refers to a path whose final component is either dot or dot-dot.
  • newpath is a path toward a non empty directory.
  • newpath contains a subpath (different from the path) toward a non existing directory.

Return

0 in case of success, -1 otherwise with error state set accordingly.

mm_close

#include <mmsysio.h>
int mm_close(int fd)

Close a file descriptor

Parameters:
  • fd (int) – file descriptor to close

Description

This function deallocates the file descriptor indicated by fd, ie it makes the file descriptor available for return by subsequent calls to mm_open() or other system functions that allocate file descriptors.

If a memory mapped file or a shared memory object remains referenced at the last close (that is, a process has it mapped), then the entire contents of the memory object persists until the memory object becomes unreferenced. If this is the last close of a memory mapped file or a shared memory object and the close results in the memory object becoming unreferenced, and the memory object has been unlinked, then the memory object will be removed.

If fd refers to a socket, mm_close() causes the socket to be destroyed.

Return

0 in case of success, -1 otherwise with error state set accordingly.

See also

mm_open()

mm_read

#include <mmsysio.h>
ssize_t mm_read(int fd, void* buf, size_t nbyte)

Reads data from a file descriptor

Parameters:
  • fd (int) – file descriptor to read from
  • buf (void*) – storage location for data
  • nbyte (size_t) – maximum size to read

Description

mm_read() attempts to read nbyte bytes from the file associated with the open file descriptor, fd, into the buffer pointed to by buf.

On files that support seeking (for example, a regular file), the mm_read() starts at a position in the file given by the file offset associated with fd. The file offset will incremented by the number of bytes actually read. * No data transfer will occur past the current end-of-file. If the starting position is at or after the end-of-file, 0 is returned.

If fd refers to a socket, mm_read() shall be equivalent to mm_recv() with no flags set.

Return

Upon successful completion, a non-negative integer is returned indicating the number of bytes actually read. Otherwise, -1 is returned and error state is set accordingly

See also

mm_recv()

mm_write

#include <mmsysio.h>
ssize_t mm_write(int fd, const void* buf, size_t nbyte)

Write data to a file descriptor

Parameters:
  • fd (int) – file descriptor to write to
  • buf (const void*) – storage location for data
  • nbyte (size_t) – amount of data to write

Description

The mm_write() function attempts to write nbyte bytes from the buffer pointed to by buf to the file associated with the open file descriptor, fd.

On a regular file or other file capable of seeking, the actual writing of data shall proceed from the position in the file indicated by the file offset associated with fd. Before successful return from mm_write(), the file offset is incremented by the number of bytes actually written.

If the O_APPEND flag of the file status flags is set, the file offset is set to the end of the file prior to each write and no intervening file modification operation will occur between changing the file offset and the write operation.

Write requests to a pipe or FIFO shall be handled in the same way as a regular file with the following exceptions

  • there is no file offset associated with a pipe, hence each write request shall append to the end of the pipe.
  • write requests of pipe buffer size bytes or less will not be interleaved with data from other processes doing writes on the same pipe.
  • a write request may cause the thread to block, but on normal completion it shall return nbyte.

Return

Upon successful completion, a non-negative integer is returned indicating the number of bytes actually written. Otherwise, -1 is returned and error state is set accordingly

mm_dup

#include <mmsysio.h>
int mm_dup(int fd)

duplicate an open file descriptor

Parameters:
  • fd (int) – file descriptor to duplicate

Description

This function creates a new file descriptor referencing the same file description as the one referenced by fd.

Note that the two file descriptors point to the same file. They will share the same file pointer.

Return

a non-negative integer representing the new file descriptor in case of success. The return file descriptor value is then guaranteed to be the lowest available at the time of the call. In case of error, -1 is returned with error state set accordingly.

mm_dup2

#include <mmsysio.h>
int mm_dup2(int fd, int newfd)

duplicate an open file descriptor to a determined file descriptor

Parameters:
  • fd (int) – file descriptor to duplicate
  • newfd (int) – file descriptor number that will become the duplicate

Description

This function duplicates an open file descriptor fd and assign it to the file descriptor newfd. In other word, this function is similar to mm_dup() but in case of success, the returned value is ensured to be newfd.

Return

a non-negative integer representing the new file descriptor in case of success. Otherwise -1 is returned with error state set accordingly.

See also

mm_dup()

mm_pipe

#include <mmsysio.h>
int mm_pipe(int pipefd)

creates an interprocess channel

Parameters:
  • pipefd (int) – array of two in receiving the read and write endpoints

Description

The mm_pipe() function creates a pipe and place two file descriptors, one each into the arguments pipefd[0] and pipefd[1], that refer to the open file descriptions for the read and write ends of the pipe. Their integer values will be the two lowest available at the time of the mm_pipe() call.

Data can be written to the file descriptor pipefd[1] and read from the file descriptor pipefd[0]. A read on the file descriptor pipefd[0] shall access data written to the file descriptor pipefd[1] on a first-in-first-out basis.

Return

0 in case of success, -1 otherwise with error state set accordingly.

mm_check_access

#include <mmsysio.h>
int mm_check_access(const char* path, int amode)

verify access to a file

Parameters:
  • path (const char*) – path of file
  • amode (int) – access mode to check (OR-combination of _OK flags)

Description

This function verify the calling process can access the file located at path according to the bits pattern specified in amode which can be a OR-combination of the R_OK, W_OK, X_OK to indicate respectively the read, write or execution access to a file. If amode is F_OK, only the existence of the file is checked.

Return

  • 0 if the file can be accessed
  • ENOENT if a component of path does not name an existing file
  • EACCESS if the file cannot be access with the mode specified in amode
  • -1 in case of error (error state is then set accordingly)

mm_isatty

#include <mmsysio.h>
int mm_isatty(int fd)

test whether a file descriptor refers to a terminal

Parameters:
  • fd (int) – File descriptor to test

Return

1 if fd refers to a terminal, 0 if not. If fd is not a valid file descriptor, -1 is returned and error state is set accordingly.

mm_chdir

#include <mmsysio.h>
int mm_chdir(const char* path)

change working directory

Parameters:
  • path (const char*) – path to new working directory

Description

The mm_chdir() function causes the directory named by the pathname pointed to by the path argument to become the current working directory; that is, the starting point for path searches for pathnames that are not absolute.

Return

0 in case of success, -1 otherwise with error state set accordingly.

mm_getcwd

#include <mmsysio.h>
char* mm_getcwd(char* buf, size_t size)

get the pathname of the current working directory

Parameters:
  • buf (char*) – pointer to buffer where to write pathname or NULL
  • size (size_t) – size of buffer pointed to by buf if not NULL

Description

The mm_getcwd() function places an absolute pathname of the current working directory in the array pointed to by buf, and return buf. The pathname copied to the array contains no components that are symbolic links. The size argument is size of the buffer pointed to by buf.

If buf is NULL, space is allocated as necessary to store the pathname. In such a case, size argument is ignored. This space may later be freed with free().

Return

a pointer to a string containing the pathname of the current working directory in case of success. Otherwise NULL is returned and error state is set accordingly.

See also

free()

mm_rmdir

#include <mmsysio.h>
int mm_rmdir(const char* path)

remove a directory

Parameters:
  • path (const char*) – path to the directory to remove

Description

The mm_rmdir() function removes the directory named by the pathname pointed to by the path argument. It only works on empty directories.

Return

0 in case of success, -1 otherwise with error state set accordingly.

mm_fstat

#include <mmsysio.h>
int mm_fstat(int fd, struct mm_stat* buf)

get file status from file descriptor

Parameters:
  • fd (int) – file descriptor
  • buf (struct mm_stat*) – pointer to mm_stat structure to fill

Description

This function obtains information about an open file associated with the file descriptor fd, and writes it to the area pointed to by buf.

Return

0 in case of success, -1 otherwise with error state set accordingly.

mm_stat

#include <mmsysio.h>
int mm_stat(const char* path, struct mm_stat* buf, int flags)

get file status from file path

Parameters:
  • path (const char*) – path of file
  • buf (struct mm_stat*) – pointer to mm_stat structure to fill
  • flags (int) – 0 or MM_NOFOLLOW

Description

This function obtains information about an file located by path, and writes it to the area pointed to by buf. If path refers to a symbolic link, the information depents on the value of flags. If flags is 0, the information returned will be the one of the target of symbol link. Otherwise, if MM_NOFOLLOW is set in flags, the information will be the one of the symbolic link itself.

Return

0 in case of success, -1 otherwise with error state set accordingly.

mm_remove

#include <mmsysio.h>
int mm_remove(const char* path, int flags)

remove a file if of type authorized in flag list

Parameters:
  • path (const char*) – path to the directory to remove
  • flags (int) – bitflag of authorized filetypes that can be removed and removal option

Description

The mm_remove() function removes a file if its type is authorized in given type flag argument. It also can remove files recursively.

The flag express whether the call is recursive and the recursivity behavior. If the MM_RECURSIVE flag is set, then the call will be recursive. Additionally, if MM_FAILONERROR is set, the removal operation will stop on the first failure it will encounter. Otherwise, it will ignore all the errors on any file or folder, and only return whether the call could be completed with full success, or any number of possible error.

Return

0 in case of success, -1 otherwise with error state set accordingly.

mm_opendir

#include <mmsysio.h>
MM_DIR* mm_opendir(const char* path)

open a directory stream

Parameters:
  • path (const char*) – path to directory

Description

The mm_opendir() function opens a directory stream corresponding to the directory named by the path argument. The directory stream is positioned at the first entry.

Return

A pointer usable with mm_readdir() on success, to be closed using mm_closedir(). In case of error, NULL is returned and an error state is set accordingly.

mm_closedir

#include <mmsysio.h>
void mm_closedir(MM_DIR* dir)

close a directory stream

Parameters:
  • dir (MM_DIR*) – directory stream to close

Description

The mm_closedir() function closes the directory stream referred to by the argument dir. Upon return, the value of dir may no longer point to an accessible object of the type MM_DIR.

mm_rewinddir

#include <mmsysio.h>
void mm_rewinddir(MM_DIR* dir)

reset a directory stream to its beginning

Parameters:
  • dir (MM_DIR*) – directory stream to rewind

Description

The mm_rewinddir() function resets the position of the directory stream to which dir refers to the beginning of the directory. It causes the directory stream to refer to the current state of the corresponding directory, as a call to mm_opendir() would have done.

See also

mm_opendir()

mm_readdir

#include <mmsysio.h>
const struct mm_dirent* mm_readdir(MM_DIR* d, int * status)

read current entry from directory stream and advance it

Parameters:
  • d (MM_DIR*) – directory stream to read
  • status (int *) – if not NULL, will contain whether readdir returned on error or end of dir

Description

The type MM_DIR represents a directory stream, which is an ordered sequence of all the directory entries in a particular directory. Directory entries present the files they contain, which may be added or removed from it asynchronously to the operation of mm_readdir().

The mm_readdir() function returns a pointer to a structure representing the directory entry at the current position in the directory stream specified by the argument dir, and position the directory stream at the next entry which will be valid until the next call to mm_readdir() with the same dir argument. It returns a NULL pointer upon reaching the end of the directory stream.

The status argument is optional. It can be provided to gather information on why the call to mm_readdir() returned NULL. Most of the time, this will happen on end-of-dir, in which case status will be 0. However this is not always the case - eg. if a required internal allocation fails - and then status is filled with a negative value.

Return

pointer to the file entry if directory stream has not reached the end. NULL otherwise. In such a case and if an error has occurred and error state is set accordingly and if status is not NULL, pointed variable will be set to -1.