Shared Memory Routines

Macros
#define	APR_SHM_NS_LOCAL
#define	APR_SHM_NS_GLOBAL

Typedefs
typedef struct apr_shm_t	apr_shm_t

Functions
	APR_DECLARE (apr_status_t) apr_shm_create(apr_shm_t **m
	APR_DECLARE (void *) apr_shm_baseaddr_get(const apr_shm_t *m)
	APR_DECLARE (apr_size_t) apr_shm_size_get(const apr_shm_t *m)
	APR_DECLARE (apr_pool_t *) apr_shm_pool_get(const apr_shm_t *theshm)

Variables
apr_size_t	reqsize
apr_size_t const char *	filename
apr_size_t const char apr_pool_t *	pool
apr_size_t const char apr_pool_t apr_int32_t	flags
apr_fileperms_t	perms
apr_fileperms_t apr_uid_t	uid
apr_fileperms_t apr_uid_t apr_gid_t	gid

Detailed Description

Macro Definition Documentation

APR_SHM_NS_GLOBAL

#define APR_SHM_NS_GLOBAL

Value:

                               2 /* Create or attach to named shared memory
                               * segment in the "Global" namespace on
                               * Windows.  (Ignored on other platforms.)
                               */

Definition at line 79 of file apr_shm.h.

APR_SHM_NS_LOCAL

#define APR_SHM_NS_LOCAL

Value:

                               1 /* Create or attach to named shared memory
                               * segment in the "Local" namespace on
                               * Windows.  (Ignored on other platforms.)
                               * By default, the "Global" namespace is
                               * used for privileged processes and the
                               * "Local" namespace is used otherwise.
                               */

Special processing flags for apr_shm_create_ex() and apr_shm_attach_ex().

Definition at line 78 of file apr_shm.h.

Typedef Documentation

apr_shm_t

typedef struct apr_shm_t apr_shm_t

Private, platform-specific data struture representing a shared memory segment.

Definition at line 44 of file apr_shm.h.

Function Documentation

APR_DECLARE() [1/4]

APR_DECLARE

(

apr_pool_t *

)

const

Get the pool used by this shared memory segment.

APR_DECLARE() [2/4]

APR_DECLARE

(

apr_size_t

)

const

Retrieve the length of a shared memory segment in bytes.

Parameters

m	The shared memory segment from which to retrieve the segment length.

APR_DECLARE() [3/4]

APR_DECLARE

(

apr_status_t

)

Create and make accessible a shared memory segment with default properties.

Parameters

m	The shared memory structure to create.
reqsize	The desired size of the segment.
filename	The file to use for shared memory on platforms that require it.
pool	the pool from which to allocate the shared memory structure.

Remarks

A note about Anonymous vs. Named shared memory segments: Not all plaforms support anonymous shared memory segments, but in some cases it is prefered over other types of shared memory implementations. Passing a NULL 'file' parameter to this function will cause the subsystem to use anonymous shared memory segments. If such a system is not available, APR_ENOTIMPL is returned.

A note about allocation sizes: On some platforms it is necessary to store some metainformation about the segment within the actual segment. In order to supply the caller with the requested size it may be necessary for the implementation to request a slightly greater segment length from the subsystem. In all cases, the apr_shm_baseaddr_get() function will return the first usable byte of memory.

Create and make accessible a shared memory segment with platform- specific processing.

Parameters

m	The shared memory structure to create.
reqsize	The desired size of the segment.
filename	The file to use for shared memory on platforms that require it.
pool	the pool from which to allocate the shared memory structure.
flags	mask of APR_SHM_* (defined above)

Remarks

A note about Anonymous vs. Named shared memory segments: Not all plaforms support anonymous shared memory segments, but in some cases it is prefered over other types of shared memory implementations. Passing a NULL 'file' parameter to this function will cause the subsystem to use anonymous shared memory segments. If such a system is not available, APR_ENOTIMPL is returned.

A note about allocation sizes: On some platforms it is necessary to store some metainformation about the segment within the actual segment. In order to supply the caller with the requested size it may be necessary for the implementation to request a slightly greater segment length from the subsystem. In all cases, the apr_shm_baseaddr_get() function will return the first usable byte of memory.

Remove named resource associated with a shared memory segment, preventing attachments to the resource, but not destroying it.

Parameters

filename	The filename associated with shared-memory segment which needs to be removed
pool	The pool used for file operations

Remarks

This function is only supported on platforms which support name-based shared memory segments, and will return APR_ENOTIMPL on platforms without such support. Removing the file while the shm is in use is not entirely portable, caller may use this to enhance obscurity of the resource, but be prepared for the call to fail, and for concurrent attempts to create a resource of the same name to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) also removes the named resource.

Delete named resource associated with a shared memory segment, preventing attachments to the resource.

Parameters

m	The shared memory segment structure to delete.

Remarks

This function is only supported on platforms which support name-based shared memory segments, and will return APR_ENOTIMPL on platforms without such support. Removing the file while the shm is in use is not entirely portable, caller may use this to enhance obscurity of the resource, but be prepared for the call to fail, and for concurrent attempts to create a resource of the same name to also fail. The pool cleanup of apr_shm_create (apr_shm_destroy) also removes the named resource.

Destroy a shared memory segment and associated memory.

Parameters

m	The shared memory segment structure to destroy.

Attach to a shared memory segment that was created by another process.

Parameters

m	The shared memory structure to create.
filename	The file used to create the original segment. (This MUST match the original filename.)
pool	the pool from which to allocate the shared memory structure for this process.

Attach to a shared memory segment that was created by another process, with platform-specific processing.

Parameters

m	The shared memory structure to create.
filename	The file used to create the original segment. (This MUST match the original filename.)
pool	the pool from which to allocate the shared memory structure for this process.
flags	mask of APR_SHM_* (defined above)

Detach from a shared memory segment without destroying it.

Parameters

m	The shared memory structure representing the segment to detach from.

Set shared memory permissions.

< File is read-only

< File is executable

< all protections

< File is read-only

< File is read-only

< Write by user

<

Deprecated:

See also

APR_FPROT_UWRITE

< Write by group

<

Deprecated:

See also

APR_FPROT_GWRITE

< Write by others

<

Deprecated:

See also

APR_FPROT_WWRITE

< Write by user

<

Deprecated:

See also

APR_FPROT_UWRITE

< Write by group

<

Deprecated:

See also

APR_FPROT_GWRITE

< Write by others

<

Deprecated:

See also

APR_FPROT_WWRITE

< File is executable

< File is executable

< Execute by user

<

Deprecated:

See also

APR_FPROT_UEXECUTE

< Execute by group

<

Deprecated:

See also

APR_FPROT_GEXECUTE

< Execute by others

<

Deprecated:

See also

APR_FPROT_WEXECUTE

< Execute by user

<

Deprecated:

See also

APR_FPROT_UEXECUTE

< Execute by group

<

Deprecated:

See also

APR_FPROT_GEXECUTE

< Execute by others

<

Deprecated:

See also

APR_FPROT_WEXECUTE

< Stat the link not the file itself if it is a link

< Stat the link not the file itself if it is a link

< ->name in proper case

< ->name in proper case

< Access Time

< Create the file if not there

< Open the file for reading

< Open the file for writing

< Delete the file after close

< Open should fail if APR_FOPEN_CREATE and file exists.

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< Read by user

<

Deprecated:

See also

APR_FPROT_UREAD

< Write by user

<

Deprecated:

See also

APR_FPROT_UWRITE

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< ->name in proper case

< Modification Time

< Access Time

< Creation or inode-changed time

< Type

< Size of the file

< Storage size consumed by the file

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< ->name in proper case

< ->name in proper case

< Type

< all protections

< ->name in proper case

< ->name in proper case

< File is read-only

< File is hidden

< File is read-only

< File is read-only

< File is hidden

< File is hidden

< Platform dependent flag to enable * non blocking file io

< Open the file for reading

< Open the file for writing

< Open the file for reading

< Open the file for writing

< Open the file for buffered I/O

< Create the file if not there

< Open should fail if APR_FOPEN_CREATE and file exists.

< Open the file and truncate to 0 length

< Open should fail if APR_FOPEN_CREATE and file exists.

< Create the file if not there

< Open the file and truncate to 0 length

< Append to the end of the file

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< Delete the file after close

< Open the file for buffered I/O

< Open the file for writing

< Open the file for writing

< Open the file for reading

< Append to the end of the file

< an atomic unix apr_stat()

< Open the file for writing

< Create the file if not there

< Open the file and truncate to 0 length

< Open the file for writing

< Create the file if not there

< Append to the end of the file

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< File is read-only

< File is executable

< all protections

< File is read-only

< File is read-only

< Write by user

<

Deprecated:

See also

APR_FPROT_UWRITE

< Write by group

<

Deprecated:

See also

APR_FPROT_GWRITE

< Write by others

<

Deprecated:

See also

APR_FPROT_WWRITE

< Write by user

<

Deprecated:

See also

APR_FPROT_UWRITE

< Write by group

<

Deprecated:

See also

APR_FPROT_GWRITE

< Write by others

<

Deprecated:

See also

APR_FPROT_WWRITE

< File is executable

< File is executable

< Execute by user

<

Deprecated:

See also

APR_FPROT_UEXECUTE

< Execute by group

<

Deprecated:

See also

APR_FPROT_GEXECUTE

< Execute by others

<

Deprecated:

See also

APR_FPROT_WEXECUTE

< Execute by user

<

Deprecated:

See also

APR_FPROT_UEXECUTE

< Execute by group

<

Deprecated:

See also

APR_FPROT_GEXECUTE

< Execute by others

<

Deprecated:

See also

APR_FPROT_WEXECUTE

< Access Time

< Stat the link not the file itself if it is a link

< Stat the link not the file itself if it is a link

< Stat the link not the file itself if it is a link

< Create the file if not there

< Open the file for reading

< Open the file for writing

< Open should fail if APR_FOPEN_CREATE and file exists.

< Delete the file after close

< Open the file for reading

< Open the file for writing

< Open the file for reading

< Open the file for writing

< Create the file if not there

< Open should fail if APR_FOPEN_CREATE and file exists.

< Open should fail if APR_FOPEN_CREATE and file exists.

< Create the file if not there

< Append to the end of the file

< Open the file and truncate to 0 length

< Platform dependent flag to enable * non blocking file io

< use OS's default permissions

<

Deprecated:

See also

APR_FPROT_OS_DEFAULT

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< Open the file for buffered I/O

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< Open the file for buffered I/O

< Open the file for writing

< Open the file for writing

< Open the file for reading

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

The problem with trying to output the entire iovec is that we cannot maintain the behaviour that a real writev would have. If we iterate over the iovec one at a time, we lose the atomic properties of writev(). The other option is to combine the entire iovec into one buffer that we could then send in one call to write(). This is not reasonable since we do not know how much data an iovec could contain.

The only reasonable option, that maintains the semantics of a real writev(), is to only write the first iovec. Callers of file_writev() must deal with partial writes as they normally would. If you want to ensure an entire iovec is written, use apr_file_writev_full().

< ->name in proper case

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< Size of the file

< Size of the file

< dev and inode

< Number of links

< ->name in proper case

< Type

< Type

< ->name in proper case

< File is read-only

< File is hidden

< File is read-only

< File is read-only

< File is hidden

< File is hidden

< Open the file for reading

< use OS's default permissions

<

Deprecated:

See also

APR_FPROT_OS_DEFAULT

< Platform dependent flag to enable * non blocking file io

< Open the file for reading

< Open the file for writing

< Create the file if not there

< Open should fail if APR_FOPEN_CREATE and file exists.

< Open the file and truncate to 0 length

< Open the file and truncate to 0 length

< Open should fail if APR_FOPEN_CREATE and file exists.

< Create the file if not there

< Delete the file after close

< Open the file for reading

< Open the file for writing

< Platform dependent tag to open the file for use across multiple threads

< Append to the end of the file

< Open the file for buffered I/O

< Platform dependent flag to enable * sparse file support, see WARNING below

< Do not register a cleanup when the file is opened. The apr_os_file_t handle in apr_file_t will not be closed when the pool is destroyed.

< Append to the end of the file

< Open the file for buffered I/O

< Open the file for writing

< Open the file for writing

< Open the file for reading

< Platform dependent tag to open the file for use across multiple threads

< Platform dependent tag to open the file for use across multiple threads

< Platform dependent tag to open the file for use across multiple threads

< Platform dependent tag to open the file for use across multiple threads

< Platform dependent tag to open the file for use across multiple threads

< Platform dependent tag to open the file for use across multiple threads

< Exclusive lock. Only one process may hold an exclusive lock at any given time. This is analogous to a "write lock".

< Platform dependent tag to open the file for use across multiple threads

< Platform dependent tag to open the file for use across multiple threads

< Platform dependent tag to open the file for use across multiple threads

< Platform dependent tag to open the file for use across multiple threads

< Size of the file

< Platform dependent tag to open the file for use across multiple threads

< Size of the file

Definition at line 74 of file apr_atomic.c.

APR_DECLARE() [4/4]

APR_DECLARE

(

void *

)

const

Retrieve the base address of the shared memory segment. NOTE: This address is only usable within the callers address space, since this API does not guarantee that other attaching processes will maintain the same address mapping.

Parameters

m	The shared memory segment from which to retrieve the base address.

Returns

address, aligned by APR_ALIGN_DEFAULT.

Variable Documentation

filename

const char * filename

Definition at line 72 of file apr_shm.h.

flags

const char apr_pool_t apr_int32_t flags

Definition at line 110 of file apr_shm.h.

gid

apr_fileperms_t apr_uid_t apr_gid_t gid

Definition at line 207 of file apr_shm.h.

perms

apr_fileperms_t perms

Definition at line 207 of file apr_shm.h.

pool

const char apr_pool_t * pool

Definition at line 73 of file apr_shm.h.

reqsize

apr_size_t reqsize

Definition at line 71 of file apr_shm.h.

uid

apr_fileperms_t apr_uid_t uid

Definition at line 207 of file apr_shm.h.