Process and shared objects

mm_spawn

#include <mmsysio.h>
int mm_spawn(mm_pid_t* child_pid, const char* file, int num_map, const struct mm_remap_fd* fd_map, int flags, char* const* argv, char* const* envp)

spawn a new process

Parameters:
  • child_pid (mm_pid_t*) – pointer receiving the child process pid
  • file (const char*) – path or basename to the executable file
  • num_map (int) – number of element in the fd_map array
  • fd_map (const struct mm_remap_fd*) – array of file descriptor remapping to pass into the child
  • flags (int) – spawn flags
  • argv (char* const*) – null-terminated array of string containing the command arguments (starting with command). Can be NULL.
  • envp (char* const*) – null-terminated array of strings specifying the environment of the executed program. If it is NULL, it inherit its environment from the calling process

Description

This function creates a new process executing the file specified by file. The pid the of created child is set in the variable pointed by child_pid.

The argument file is used to construct a pathname that identifies the child process image file. If the file argument contains a directory separator character, it will be used as the pathname for this file. Otherwise, the path prefix for this file is obtained by a search of the list of directories passed as the environment variable PATH. The list is searched from beginning to end, applying the filename to each prefix, until an executable file with the specified name and appropriate execution permissions is found. On Windows platform, the filename will be tried first as is and then with .exe extension.

The child process will inherit only the open file descriptors specified in the fd_map array whose length is indicated by num_map. For each element in fd_map, a file descriptor numbered as specified in mm_remap_fd.child_fd is available at child startup referencing the same file description as the corresponding mm_remap_fd.parent_fd in the calling process. This means that after successful execution of mm_spawn() two reference of the same file will exist and the underlying file will be actually closed when all file descriptor referencing it will be closed. The fd_map array is processed sequentially so a mapping in the first element can be overridden in the next elements. If an element in fd_map has a mm_remap_fd.parent_fd field set to -1, it means that the corresponding fd_map has a mm_remap_fd.child_fd must not opened in the child process.

For convenience, the standard input, output and error are inherited by default in the child process. If any of those file are meant to be closed or redirected in the child, this can simply be done by adding element in fd_map that redirect a standard file descriptor in the parent, or close them (by setting mm_remap_fd.parent_fd to -1.

flags must contains a OR-combination or 0 or any number of the following flags :

MM_SPAWN_DAEMONIZE
the created process will be detached from calling process and will survive to its parent death (a daemon in the UNIX terminology).
MM_SPAWN_KEEP_FDS
All open file descriptors in the calling process that are inherintable are kept in the child with the same index. All the other file descriptor are closed. Unless specified otherwise, all file descriptor created in mmlib API are not inheritable. If this flag is specified, num_map and fd_map argument are ignored.

The argument argv, if not null, is an array of character pointers to null-terminated strings. The application shall ensure that the last member of this array is a null pointer. These strings constitutes the argument list available to the new process image. The value in argv[0] should point to a filename that is associated with the process being started. If argv is NULL, the behavior is as if mm_spawn() were called with a two array argument, argv[0] = file, argv[1] = NULL.

The argument envp is an array of character pointers to null-terminated strings. These strings constitutes the environment for the new process image. The envp array is terminated by a null pointer. If envp is NULL, the new process use the same environment of the calling process at the time of the mm_spawn() call.

Return

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

mm_execv

#include <mmsysio.h>
int mm_execv(const char* file, int num_map, const struct mm_remap_fd* fd_map, int flags, char* const* argv, char* const* envp)

replace executable image of the calling process

Parameters:
  • file (const char*) – path or basename to the executable file
  • num_map (int) – number of element in the fd_map array
  • fd_map (const struct mm_remap_fd*) – array of file descriptor remapping to pass in the new image
  • flags (int) – spawn flags
  • argv (char* const*) – null-terminated array of string containing the command arguments (starting with command). Can be NULL.
  • envp (char* const*) – null-terminated array of strings specifying the environment of the executed program. If it is NULL, it inherit its environment from the calling process

Description

This function is the same as mm_spawn() excepting that, instead of creating a new child process, it replaces the current process image with a new process image. There shall be no return from a successful call, because the calling process image is overlaid by the new process image. Hence the PID number of calling process can still be used with mm_wait_process() to wait for the new process image to finish.

As a consequence, MM_SPAWN_DAEMONIZE flag is meaningless in the context of mm_execv(). Hence, this is not an accepted value for flags.

NOTE

Beware, on some platform, you are not ensured that the PID of the process image will remains the exactly same. However on those, the old process, when it calls mm_execv(), will free as much resources it can (terminates all threads and close all fds) and spawn the new process image. It will then remain available during the lifetime of the new image process and usable with mm_wait_process() if the old process image was created with mm_spawn().

Return

the function will NOT return in case of success. Otherwise, -1 is returned and error state is set accordingly.

mm_wait_process

#include <mmsysio.h>
int mm_wait_process(mm_pid_t pid, int* status)

wait for a child process to terminate

Parameters:
  • pid (mm_pid_t) – PID of child process
  • status (int*) – location where to put status of the child process

Description

This function get the status of a the child process whose PID is pid. If the child process is not terminated yet, the function will block until the child is terminated.

If status is not NULL, it refers to a location that will receive the status information of the terminated process. The information is a mask of MM_WSTATUS_* indicating whether the child has terminated because of normal termination or abnormal one and the exit code (or signal number). To be accessible in the status information, the return code of a child program must be between 0 and 255.

Return

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

mm_mapfile

#include <mmsysio.h>
void* mm_mapfile(int fd, mm_off_t offset, size_t len, int mflags)

map pages of memory

Parameters:
  • fd (int) – file descriptor of file to map in memory
  • offset (mm_off_t) – offset within the file from which the mapping must start
  • len (size_t) – length of the mapping
  • mflags (int) – control how the mapping is done

Description

The mm_mapfile() function establishes a mapping between a process’ address space and a portion or the entirety of a file or shared memory object represented by fd. The portion of the object to map can be controlled by the parameters offset and len. offset must be a multiple of page size.

The flags in parameters mflags determines whether read, write, execute, or some combination of accesses are permitted to the data being mapped. The requested access can of course cannot grant more permission than the one associated with fd. It must be one of the following flags :

MM_MAP_SHARED
Modifications to the mapped data are propagated to the underlying object.
MM_MAP_PRIVATE
Modifications to the mapped data will be visible only to the calling process and shall not change the underlying object.

In addition to the previous flag, mflags can contain a OR-combination of the following flags :

MM_MAP_READ
Data can be read
MM_MAP_WRITE
Data can be written
MM_MAP_EXEC
Data can be executed
MM_MAP_RDWR
alias to MM_MAP_READ|MM_MAP_WRITE

The mm_mapfile() function adds an extra reference to the file associated with the file descriptor fd which is not removed by a subsequent mm_close() on that file descriptor. This reference will be removed when there are no more mappings to the file.

On windows platforms only, when mapping a file, the requested size MUST be lesser than or equal to the size of the file. Raise EOVERFLOW otherwise.

Return

The starting address of the mapping in case of success. Otherwise NULL is returned and error state is set accordingly.

See also

mm_close()

mm_unmap

#include <mmsysio.h>
int mm_unmap(void* addr)

unmap pages of memory

Parameters:
  • addr (void*) – starting address of memory block to unmap

Description

Remove a memory mapping previously established. addr must be NULL or must have been returned by a successful call to mm_mapfile(). If addr is NULL, mm_unmap() do nothing.

Return

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

See also

mm_mapfile()

mm_anon_shm

#include <mmsysio.h>
int mm_anon_shm(void)

Creates an anonymous memory object

Parameters:
  • void – no arguments

Description

This function creates an anonymous shared memory object (ie nameless) and establishes a connection between it and a file descriptor. If successful, the file descriptor for the shared memory object is the lowest numbered file descriptor not currently open for that process.

Return

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

mm_shm_open

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

open a shared memory object

Parameters:
  • name (const char*) – name of the shared memory object
  • oflag (int) – flags controlling the open operation
  • mode (int) – permission if object is created

Description

This function establishes a connection between a shared memory object and a file descriptor. The name argument points to a string naming a shared memory object. If successful, the file descriptor for the shared memory object is the lowest numbered file descriptor not currently open for that process.

The file status flags and file access modes of the open file description are according to the value of oflag. It must contains the exactly one of the following: O_RDONLY, O_RDWR. It can contains any combination of the remaining flags: O_CREAT, O_EXCL, O_TRUNC. The meaning of these constant is exactly the same as for mm_open().

When a shared memory object is created, the state of the shared memory object, including all data associated with the shared memory object, persists until the shared memory object is unlinked and all other references are gone. It is unspecified whether the name and shared memory object state remain valid after a system reboot.

Once a new shared memory object has been created, it can be removed with a call to mm_shm_unlink().

Return

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