OSSymbol

Inherits from
OSString
Availability
Available in OS X v10.0 and later.
Declared in
OSSymbol.h

Overview

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

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.

Tasks

Miscellaneous

Instance Methods

free

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

virtual void free();
Discussion

Because OSSymbol shares instances, the reference-counting functions must synchronize access to the class-internal tables used to track those instances.

initWithCString

Overridden to prevent creation of duplicate symbols.

virtual bool initWithCString( const char *cString);
Parameters
cString

Unused.

Return Value

false.

Discussion

Overrides OSString's implementation to prevent creation of distinct OSSymbols with the same string value.

initWithCStringNoCopy

Overridden to prevent creation of duplicate symbols.

virtual bool initWithCStringNoCopy( const char *cString);
Parameters
cString

Unused.

Return Value

false.

Discussion

Overrides OSString's implementation to prevent creation of distinct OSSymbols with the same string value.

initWithString

Overridden to prevent creation of duplicate symbols.

virtual bool initWithString( const OSString *aString);
Parameters
aString

Unused.

Return Value

false.

Discussion

Overrides OSString's implementation to prevent creation of distinct OSSymbols with the same string value.

isEqualTo

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

virtual bool isEqualTo( const OSMetaClassBase *anObject) const;
Parameters
anObject

The object to be compared against the receiver.

Return Value

Returns true if the two objects are equivalent, false otherwise.

Discussion

An OSSymbol is considered equal to another object if that object is derived from OSString and contains the equivalent bytes of the same length.

isEqualTo(const char *)

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

virtual bool isEqualTo( const char *cString) const;
Parameters
cString

The C string to compare against the receiver.

Return Value

true if the OSSymbol's characters are equivalent to the C string's, false otherwise.

isEqualTo(const OSSymbol *)

Tests the equality of two OSSymbol objects.

virtual bool isEqualTo( const OSSymbol *aSymbol) const;
Parameters
aSymbol

The OSSymbol object being compared against the receiver.

Return Value

true if the two OSSymbol objects are equivalent, false otherwise.

Discussion

Two OSSymbol objects are considered equal if they have the same address; that is, this function is equivalent to the == operator.

taggedRelease(const void *)

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

virtual void taggedRelease( const void *tag) const;
Parameters
tag

Used for tracking collection references.

Discussion

Because OSSymbol shares instances, the reference-counting functions must synchronize access to the class-internal tables used to track those instances.

taggedRelease(const void *, const int)

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

virtual void taggedRelease( const void *tag, const int freeWhen) const;
Parameters
tag

Used for tracking collection references.

freeWhen

If decrementing the reference count makes it >= freeWhen, the object is immediately freed.

Discussion

Because OSSymbol shares instances, the reference-counting functions must synchronize access to the class-internal tables used to track those instances.

withCString

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

static const OSSymbol * withCString( const char *cString);
Parameters
cString

The C string to look up or copy.

Return Value

An instance of OSSymbol representing the same characters as cString; NULL on failure.

Discussion

This function returns the unique OSSymbol instance representing the string value of cString. You can compare it with other OSSymbols using the == operator.

OSSymbols are reference-counted normally. This function either returns a new OSSymbol with a retain count of 1, or increments the retain count of the existing instance.

withCStringNoCopy

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

static const OSSymbol * withCStringNoCopy( const char *cString);
Parameters
cString

The C string to look up or use.

Return Value

An instance of OSSymbol representing the same characters as cString; NULL.

Discussion

Avoid using this function; OSSymbols should own their internal string buffers.

This function returns the unique OSSymbol instance representing the string value of cString. You can compare it with other OSSymbols using the == operator.

OSSymbols are reference-counted normally. This function either returns a new OSSymbol with a retain count of 1, or increments the retain count of the existing instance.

withString

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

static const OSSymbol * withString( const OSString *aString);
Parameters
aString

The OSString object to look up or copy.

Return Value

An instance of OSSymbol representing the same characters as aString; NULL on failure.

Discussion

This function creates or returns the unique OSSymbol instance representing the string value of aString. You can compare it with other OSSymbols using the == operator.

OSSymbols are reference-counted normally. This function either returns a new OSSymbol with a retain count of 1, or increments the retain count of the existing instance.