Class

OSSymbol

OSSymbol wraps a C string in a unique C++ object for use as keys in Libkern collections.

Declaration

class OSSymbol

Overview

OSSymbol is a container class for managing uniqued strings, for example, those used as dictionary keys. Its static instance-creation functions check for an existing instance of OSSymbol with the requested C string value before creating a new object. If an instance already exists in the pool of unique symbols, its reference count is incremented and the existing instance is returned.

While OSSymbol provides for uniquing of a given string value, it makes no effort to enforce immutability of that value. Altering the contents of an OSSymbol should be avoided.

Use Restrictions

With very few exceptions in the I/O Kit, all Libkern-based C++ classes, functions, and macros are unsafe to use in a primary interrupt context. Consult the I/O Kit documentation related to primary interrupts for more information.

OSSymbol provides no concurrency protection; it's up to the usage context to provide any protection necessary. Some portions of the I/O Kit, such as IORegistryEntry, handle synchronization via defined member functions for setting properties.

Topics

Miscellaneous

- free

Overrides OSObject::free to synchronize with the symbol pool.

- initWithCString

Overridden to prevent creation of duplicate symbols.

- initWithCStringNoCopy

Overridden to prevent creation of duplicate symbols.

- initWithString

Overridden to prevent creation of duplicate symbols.

- isEqualTo

Tests the equality of an OSSymbol object to an arbitrary object.

- isEqualTo(const char *)

Tests the equality of an OSSymbol object with a C string.

- isEqualTo(const OSSymbol *)

Tests the equality of two OSSymbol objects.

- taggedRelease(const void *)

Overrides OSObject::taggedRelease(const void *) to synchronize with the symbol pool.

- taggedRelease(const void *, const int)

Overrides OSObject::taggedRelease(const void *, const int) to synchronize with the symbol pool.

- withCString

Returns an OSSymbol created from a C string, or the existing unique instance of the same value.

- withCStringNoCopy

Returns an OSSymbol created from a C string, without copying that string, or the existing unique instance of the same value.

- withString

Returns an OSSymbol created from an OSString, or the existing unique instance of the same value.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software