Description
Raised when an operating-system backing or mapping operation fails.
Attach_Region
procedure Attach_Region (Item : Mapping; Region : in out Flyology.Data_Structures.Regions.View)
Attach a process-local Data_Structures region view to the complete mapping without exposing its native address. Detach every nested structure view and Region before unmapping.
Parameters
- Item
Live mapping borrowed by Region
- Region
Detached region view to attach
Raised exceptions
- Validation_Error
Item is not mapped
Backing_Kind
type Backing_Kind is (Anonymous_Capability, Named_POSIX, File_Backed, Received_Capability);
Kind of backing object represented by an owned descriptor.
Enumeration literals
- Anonymous_Capability
Anonymous memfd on Linux or immediately unlinked POSIX shared-memory object on Darwin
- Named_POSIX
Named POSIX shared-memory object
- File_Backed
Regular file opened without following symlinks where the host supports that flag
- Received_Capability
Descriptor received through SCM_RIGHTS
Backing_Object
type Backing_Object is limited private;
Limited owner of one backing descriptor. Close is independent of any mappings already created from the descriptor. Finalization attempts a non-raising close but never unlinks a named object or file.
Byte_Length
subtype Byte_Length is Flyology.Data_Structures.Byte_Count;
Fixed-width byte length shared with relocatable data structures.
Close
procedure Close (Item : in out Backing_Object)
Close Item's descriptor. The operation is idempotent and does not invalidate live mappings or unlink namespace entries.
Parameters
- Item
Descriptor owner to close
Raised exceptions
- Operating_System_Error
Closing reports an error
Create_Anonymous
procedure Create_Anonymous
(Item : in out Backing_Object; Length : Byte_Length; Require_No_Execute_Seal : Boolean := False)
Create anonymous capability-backed storage at an exact positive size. Linux always requires immutable size seals and tries MFD_NOEXEC_SEAL, falling back only when the running kernel does not recognize it. Darwin uses an unpredictable exclusive mode-0600 POSIX shm name and unlinks it before returning. Contents remain writable through shared mappings.
Parameters
- Item
Closed owner that receives the new descriptor
- Length
Exact positive byte length
- Require_No_Execute_Seal
Reject hosts without an applied Linux no-execute seal
Raised exceptions
- Constraint_Error
Length is zero or not natively representable
- Security_Error
A required seal or descriptor property fails
- Operating_System_Error
Creation or exact sizing fails
Create_File
procedure Create_File
(Item : in out Backing_Object;
Path : String;
Length : Byte_Length;
Permissions : Permission_Bits := 8#600#)
Exclusively create and exactly size a regular file without following a final symlink where supported. Close does not unlink the path.
Parameters
- Item
Closed owner that receives the new descriptor
- Path
Nonempty file path without a NUL byte
- Length
Exact positive byte length
- Permissions
Requested creation permissions, normally 0600
Raised exceptions
- Constraint_Error
Path or length is invalid
- Validation_Error
The created object is not a regular file
- Operating_System_Error
Creation or sizing fails
Create_Named
procedure Create_Named
(Item : in out Backing_Object;
Name : String;
Length : Byte_Length;
Permissions : Permission_Bits := 8#600#)
Exclusively create and exactly size a named POSIX shared-memory object. The name must begin with one slash and contain no other slash. Close does not unlink it; call Unlink explicitly.
Parameters
- Item
Closed owner that receives the new descriptor
- Name
POSIX shared-memory name
- Length
Exact positive byte length
- Permissions
Requested creation permissions, normally 0600
Raised exceptions
- Constraint_Error
Name or length is invalid
- Operating_System_Error
Exclusive creation or sizing fails
Create_Or_Open_Named
procedure Create_Or_Open_Named
(Item : in out Backing_Object;
Name : String;
Length : Byte_Length;
Result : out Namespace_Open_Result;
Permissions : Permission_Bits := 8#600#)
Exclusively create a named object or open the winner's object. An opener racing the creator before exact sizing receives Initialization_In_Progress with Item closed; bytes are never repaired or overwritten by an opener.
Parameters
- Item
Closed owner that receives a ready descriptor
- Name
POSIX shared-memory name
- Length
Exact required byte length
- Result
Created, opened, or initialization-in-progress result
- Permissions
Requested permissions when this caller creates
Raised exceptions
- Constraint_Error
Name or length is invalid
- Validation_Error
Existing type or nonzero size does not match
- Operating_System_Error
Namespace or sizing operation fails
Flush
procedure Flush (Item : Backing_Object)
Request descriptor-level persistence with fsync. This is meaningful for file-backed objects and is not an application transaction protocol.
Parameters
- Item
Open backing object to flush
Raised exceptions
- Validation_Error
Item is closed
- Operating_System_Error
Flushing fails
Flush
procedure Flush (Item : Mapping; Synchronous : Boolean := True)
Flush dirty mapping pages according to the selected synchronous or asynchronous msync policy. For file-backed durability, also call Flush on the backing object. Neither operation supplies crash-consistent application transactions.
Parameters
- Item
Live mapping to flush
- Synchronous
Wait for page writeback when True
Raised exceptions
- Validation_Error
Item is not mapped
- Operating_System_Error
Flushing fails
Is_Mapped
function Is_Mapped (Item : Mapping) return Boolean
Report whether Item owns a live mapping.
Parameters
- Item
Mapping owner to inspect
Return value
True after Map and before Unmap
Is_Open
function Is_Open (Item : Backing_Object) return Boolean
Report whether Item owns an open descriptor.
Parameters
- Item
Owner to inspect
Return value
True while Close has not consumed the descriptor
Kind
function Kind (Item : Backing_Object) return Backing_Kind
Return the recorded backing kind.
Parameters
- Item
Open owner to inspect
Return value
Backing kind established at creation, open, or receive
Raised exceptions
- Validation_Error
Item is closed
Length
function Length (Item : Backing_Object) return Byte_Length
Return the exactly validated object length.
Parameters
- Item
Open owner to inspect
Return value
Exact byte length, or zero while closed
Length
function Length (Item : Mapping) return Byte_Length
Return the live mapping length, or zero while unmapped.
Parameters
- Item
Mapping owner to inspect
Return value
Complete mapped byte length
Map
procedure Map (Item : in out Mapping; Source : Backing_Object)
Map the complete backing object shared, readable, and writable at an operating-system-selected address. No fixed address or execute permission is requested.
Parameters
- Item
Closed mapping owner that receives the mapping
- Source
Open backing object borrowed only for this call
Raised exceptions
- Validation_Error
Item is mapped or Source is closed
- Operating_System_Error
Mapping fails
Mapping
type Mapping is limited private;
Limited owner of one process-local shared read/write mapping. The mapping never requests execute permission. Every structure and region view borrowing its bytes must detach before Unmap or finalization.
Namespace_Open_Result
type Namespace_Open_Result is (Created_New, Opened_Existing, Initialization_In_Progress);
Result of opening a namespace object that another process may still be sizing. Initialization_In_Progress leaves the output object closed.
Enumeration literals
- Created_New
This caller created and exactly sized the object
- Opened_Existing
An existing object passed exact-size validation
- Initialization_In_Progress
The object exists but still has zero length; retry only at an application-selected scheduling point
Open_File
procedure Open_File (Item : in out Backing_Object; Path : String; Expected_Length : Byte_Length)
Open an existing regular file without following a final symlink where supported and require its exact size.
Parameters
- Item
Closed owner that receives the descriptor
- Path
Nonempty file path without a NUL byte
- Expected_Length
Required positive byte length
Raised exceptions
- Constraint_Error
Path or length is invalid
- Validation_Error
Object type or size does not match
- Operating_System_Error
Opening or validation fails
Open_Named
procedure Open_Named
(Item : in out Backing_Object;
Name : String;
Expected_Length : Byte_Length;
Result : out Namespace_Open_Result)
Open an existing named object only when its size exactly matches. A zero-sized object is reported as initialization in progress and Item remains closed. Any other size mismatch fails closed.
Parameters
- Item
Closed owner that receives a ready descriptor
- Name
POSIX shared-memory name
- Expected_Length
Required positive byte length
- Result
Existing-ready or initialization-in-progress result
Raised exceptions
- Constraint_Error
Name or length is invalid
- Validation_Error
Type or nonzero size does not match
- Operating_System_Error
Opening or validation fails
Operating_System_Error
Operating_System_Error : exception;
Raised when an operating-system backing or mapping operation fails.
Permission_Bits
subtype Permission_Bits is Interfaces.Unsigned_32 range 0 .. 8#777#;
POSIX permission bits accepted when creating named or file objects.
Properties
function Properties (Item : Backing_Object) return Security_Properties
Return descriptor properties verified when Item was acquired.
Parameters
- Item
Open owner to inspect
Return value
Verified security properties
Raised exceptions
- Validation_Error
Item is closed
Security_Error
Security_Error : exception;
Raised when a requested descriptor security property is unavailable.
Security_Properties
type Security_Properties is record
Close_On_Exec : Boolean := False;
Size_Immutable : Boolean := False;
No_Execute_Seal : Boolean := False;
No_Execute_Seal_Supported : Boolean := False;
No_Symlink_Follow : Boolean := False;
Owner_Only_Permissions : Boolean := False;
end record;
Security properties verified on the live descriptor.
Record fields
- Close_On_Exec
FD_CLOEXEC is set
- Size_Immutable
Linux grow, shrink, and further-seal seals are set
- No_Execute_Seal
Linux MFD_NOEXEC_SEAL was accepted by the kernel
- No_Execute_Seal_Supported
The running Linux kernel recognized MFD_NOEXEC_SEAL
- No_Symlink_Follow
File opening used O_NOFOLLOW
- Owner_Only_Permissions
Group and other permission bits are clear; Linux memfd objects are capability-only but normally report this as False because their inode mode bits are not the access boundary
Unlink
procedure Unlink (Item : in out Backing_Object)
Remove Item's named POSIX object or file namespace entry. Where the host exposes stable object identity, reject a name that no longer identifies Item's open descriptor. Callers must always exclude concurrent unlink- and-replacement until this call returns: identity comparison and unlink are separate operations, and Darwin POSIX shm descriptors expose no stable identity for this comparison. The call is explicit, idempotent after success, and independent of live mappings. Anonymous objects are already unlinked or unnamed.
Parameters
- Item
Owned backing object whose saved namespace entry is removed
Raised exceptions
- Validation_Error
Item is closed or the name was replaced
- Operating_System_Error
Unlinking fails
Unmap
procedure Unmap (Item : in out Mapping)
Unmap Item. The operation is idempotent and independent of the backing descriptor, but all borrowed views must already be detached.
Parameters
- Item
Mapping owner to release
Raised exceptions
- Operating_System_Error
Unmapping fails
Validation_Error
Validation_Error : exception;
Raised when an exact size, object type, or namespace invariant fails.