<!--
{
  "availability" : [
    "iOS: -",
    "iPadOS: -",
    "macCatalyst: -",
    "macOS: -",
    "tvOS: -",
    "visionOS: -",
    "watchOS: -"
  ],
  "documentType" : "symbol",
  "framework" : "CoreFoundation",
  "identifier" : "/documentation/CoreFoundation/CFURL",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Core Foundation"
    ],
    "preciseIdentifier" : "c:@T@CFURLRef"
  },
  "title" : "CFURL"
}
-->

# CFURL

```
class CFURL
```

## Overview

The `CFURL` opaque type provides facilities for creating, parsing, and dereferencing URL strings. `CFURL` is useful to applications that need to use URLs to access resources, including local files.

A `CFURL` object is composed of two parts—a base URL, which can be `NULL`, and a string that is resolved relative to the base URL. A `CFURL` object whose string is fully resolved without a base URL is considered absolute; all others are considered relative.

`CFURL` is “toll-free bridged” with its Cocoa Foundation counterpart, <doc://com.apple.documentation/documentation/Foundation/NSURL>. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. In other words, in a method where you see an `NSURL *` parameter, you can pass in a `CFURLRef`, and in a function where you see a `CFURLRef` parameter, you can pass in an `NSURL` instance. This also applies to concrete subclasses of `NSURL`. See [Toll-Free Bridged Types](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFDesignConcepts/Articles/tollFreeBridgedTypes.html#//apple_ref/doc/uid/TP40010677) for more information on toll-free bridging.

Starting in OS X v10.6, the `CFURL` opaque type provides a facility for creating and using bookmarks. A *bookmark* provides a persistent reference to a file-system resource. When you resolve a bookmark, you obtain a URL to the resource’s current location. A bookmark’s association with a file-system resource (typically a file or folder) usually continues to work if the user moves or renames the resource, or if the user relaunches your app or restarts the system.

In a macOS app that adopts App Sandbox, to gain persistent access to a file-system resource you must use a *security-scoped bookmark*. Such a bookmark preserves, across app launches, a user’s intent to give your app access to a resource. For details on how this works, including information on the entitlements you need in your Xcode project, read [Security-Scoped Bookmarks and Persistent Resource Access](https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) in [App Sandbox Design Guide](https://developer.apple.com/library/archive/documentation/Security/Conceptual/AppSandboxDesignGuide/AboutAppSandbox/AboutAppSandbox.html#//apple_ref/doc/uid/TP40011183).

When you resolve a security-scoped bookmark, you get a security-scoped URL. The file system resource that the URL points to is not available for use inside your app’s sandbox until you call the [`CFURLStartAccessingSecurityScopedResource(_:)`](/documentation/CoreFoundation/CFURLStartAccessingSecurityScopedResource(_:)) function (or its Cocoa equivalent, the <doc://com.apple.documentation/documentation/Foundation/NSURL/startAccessingSecurityScopedResource()> method) on the URL.

When you no longer need access to a resource that you obtained using security scope (typically, after you close the resource) you must call the [`CFURLStopAccessingSecurityScopedResource(_:)`](/documentation/CoreFoundation/CFURLStopAccessingSecurityScopedResource(_:)) method (or its Cocoa equivalent, the <doc://com.apple.documentation/documentation/Foundation/NSURL/stopAccessingSecurityScopedResource()> method) on the resource’s URL.

> Warning:
> You must balance every call to the ``doc://com.apple.corefoundation/documentation/CoreFoundation/CFURLStartAccessingSecurityScopedResource(_:)`` method with a corresponding call to the ``doc://com.apple.corefoundation/documentation/CoreFoundation/CFURLStopAccessingSecurityScopedResource(_:)`` method. If you fail to relinquish your access when you no longer need a file-system resource, your app leaks kernel resources. If sufficient kernel resources are leaked, your app loses its ability to add file-system locations to its sandbox, such as via Powerbox or security-scoped bookmarks, until relaunched.

The functions for using security-scoped bookmarks are described in this document in Working with Bookmark Data. For a general introduction to using bookmarks in macOS, read [Locating Files Using Bookmarks](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/AccessingFilesandDirectories/AccessingFilesandDirectories.html#//apple_ref/doc/uid/TP40010672-CH3-SW10) in [File System Programming Guide](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/Introduction/Introduction.html#//apple_ref/doc/uid/TP40010672).

When you copy a security-scoped URL (as obtained from a security-scoped bookmark), the copy has the security scope of the original. You gain access to the file-system resource (that the URL points to) just as you would with the original URL: by calling the [`CFURLStartAccessingSecurityScopedResource(_:)`](/documentation/CoreFoundation/CFURLStartAccessingSecurityScopedResource(_:)) function (or its Cocoa equivalent).

If you need a security-scoped URL’s path as a string value (as provided by the [`CFURLGetString(_:)`](/documentation/CoreFoundation/CFURLGetString(_:)) function), such as to provide to an API that requires a string value, obtain the path from the URL as needed. Note, however, that a string-based path obtained from a security-scoped URL *does not* have security scope and you cannot use that string to obtain access a security-scoped resource.

`CFURL` fails to create an object if the string passed is not well-formed (that is, if it does not comply with RFC 2396). Examples of cases that will not succeed are strings containing space characters and high-bit characters. If a function fails to create a `CFURL` object, it returns `NULL`, which you must be prepared to handle. If you create `CFURL` objects using file system paths, you should use the [`CFURLCreateFromFileSystemRepresentation(_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateFromFileSystemRepresentation(_:_:_:_:)) and [`CFURLCreateFromFileSystemRepresentationRelativeToBase(_:_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateFromFileSystemRepresentationRelativeToBase(_:_:_:_:_:)) functions, which handle the subtle differences between URL paths and file system paths.

For functions that read and write data from a URL, see [Core Foundation URL Access Utilities](/documentation/CoreFoundation/core-foundation-url-access-utilities)

## Topics

### Creating a CFURL

[`CFURLCopyAbsoluteURL(_:)`](/documentation/CoreFoundation/CFURLCopyAbsoluteURL(_:))

Creates a new `CFURL` object by resolving the relative portion of a URL against its base.

[`CFURLCreateAbsoluteURLWithBytes(_:_:_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateAbsoluteURLWithBytes(_:_:_:_:_:_:))

Creates a new `CFURL` object by resolving the relative portion of a URL, specified as bytes, against its given base URL.

[`CFURLCreateByResolvingBookmarkData(_:_:_:_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateByResolvingBookmarkData(_:_:_:_:_:_:_:))

Returns a new URL made by resolving bookmark data.

[`CFURLCreateCopyAppendingPathComponent(_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateCopyAppendingPathComponent(_:_:_:_:))

Creates a copy of a given URL and appends a path component.

[`CFURLCreateCopyAppendingPathExtension(_:_:_:)`](/documentation/CoreFoundation/CFURLCreateCopyAppendingPathExtension(_:_:_:))

Creates a copy of a given URL and appends a path extension.

[`CFURLCreateCopyDeletingLastPathComponent(_:_:)`](/documentation/CoreFoundation/CFURLCreateCopyDeletingLastPathComponent(_:_:))

Creates a copy of a given URL with the last path component deleted.

[`CFURLCreateCopyDeletingPathExtension(_:_:)`](/documentation/CoreFoundation/CFURLCreateCopyDeletingPathExtension(_:_:))

Creates a copy of a given URL with its last path extension removed.

[`CFURLCreateFilePathURL(_:_:_:)`](/documentation/CoreFoundation/CFURLCreateFilePathURL(_:_:_:))

Returns a new file path URL that refers to the same resource as a specified URL.

[`CFURLCreateFileReferenceURL(_:_:_:)`](/documentation/CoreFoundation/CFURLCreateFileReferenceURL(_:_:_:))

Returns a new file reference URL that points to the same resource as a specified URL.

[`CFURLCreateFromFileSystemRepresentation(_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateFromFileSystemRepresentation(_:_:_:_:))

Creates a new `CFURL` object for a file system entity using the native representation.

[`CFURLCreateFromFileSystemRepresentationRelativeToBase(_:_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateFromFileSystemRepresentationRelativeToBase(_:_:_:_:_:))

Creates a `CFURL` object from a native character string path relative to a base URL.

[`CFURLCreateFromFSRef(_:_:)`](/documentation/CoreFoundation/CFURLCreateFromFSRef(_:_:))

Creates a URL from a given directory or file.

[`CFURLCreateWithBytes(_:_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateWithBytes(_:_:_:_:_:))

Creates a `CFURL` object using a given character bytes.

[`CFURLCreateWithFileSystemPath(_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateWithFileSystemPath(_:_:_:_:))

Creates a `CFURL` object using a local file system path string.

[`CFURLCreateWithFileSystemPathRelativeToBase(_:_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateWithFileSystemPathRelativeToBase(_:_:_:_:_:))

Creates a `CFURL` object using a local file system path string relative to a base URL.

[`CFURLCreateWithString(_:_:_:)`](/documentation/CoreFoundation/CFURLCreateWithString(_:_:_:))

Creates a `CFURL` object using a given `CFString` object.

### Accessing the Parts of a URL

[`CFURLCanBeDecomposed(_:)`](/documentation/CoreFoundation/CFURLCanBeDecomposed(_:))

Determines if the given URL conforms to RFC 1808 and therefore can be decomposed.

[`CFURLCopyFileSystemPath(_:_:)`](/documentation/CoreFoundation/CFURLCopyFileSystemPath(_:_:))

Returns the path portion of a given URL.

[`CFURLCopyFragment(_:_:)`](/documentation/CoreFoundation/CFURLCopyFragment(_:_:))

Returns the fragment from a given URL.

[`CFURLCopyHostName(_:)`](/documentation/CoreFoundation/CFURLCopyHostName(_:))

Returns the host name of a given URL.

[`CFURLCopyLastPathComponent(_:)`](/documentation/CoreFoundation/CFURLCopyLastPathComponent(_:))

Returns the last path component of a given URL.

[`CFURLCopyNetLocation(_:)`](/documentation/CoreFoundation/CFURLCopyNetLocation(_:))

Returns the net location portion of a given URL.

[`CFURLCopyParameterString(_:_:)`](/documentation/CoreFoundation/CFURLCopyParameterString(_:_:))

Returns the parameter string from a given URL.

[`CFURLCopyPassword(_:)`](/documentation/CoreFoundation/CFURLCopyPassword(_:))

Returns the password of a given URL.

[`CFURLCopyPath(_:)`](/documentation/CoreFoundation/CFURLCopyPath(_:))

Returns the path portion of a given URL.

[`CFURLCopyPathExtension(_:)`](/documentation/CoreFoundation/CFURLCopyPathExtension(_:))

Returns the path extension of a given URL.

[`CFURLCopyQueryString(_:_:)`](/documentation/CoreFoundation/CFURLCopyQueryString(_:_:))

Returns the query string of a given URL.

[`CFURLCopyResourceSpecifier(_:)`](/documentation/CoreFoundation/CFURLCopyResourceSpecifier(_:))

Returns any additional resource specifiers after the path.

[`CFURLCopyScheme(_:)`](/documentation/CoreFoundation/CFURLCopyScheme(_:))

Returns the scheme portion of a given URL.

[`CFURLCopyStrictPath(_:_:)`](/documentation/CoreFoundation/CFURLCopyStrictPath(_:_:))

Returns the path portion of a given URL.

[`CFURLCopyUserName(_:)`](/documentation/CoreFoundation/CFURLCopyUserName(_:))

Returns the user name from a given URL.

[`CFURLGetPortNumber(_:)`](/documentation/CoreFoundation/CFURLGetPortNumber(_:))

Returns the port number from a given URL.

[`CFURLHasDirectoryPath(_:)`](/documentation/CoreFoundation/CFURLHasDirectoryPath(_:))

Determines if a given URL’s path represents a directory.

### Converting URLs to Other Representations

[`CFURLCreateData(_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateData(_:_:_:_:))

Creates a `CFData` object containing the content of a given URL.

[`CFURLCreateStringByAddingPercentEscapes(_:_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateStringByAddingPercentEscapes(_:_:_:_:_:))

Creates a copy of a string, replacing certain characters with the equivalent percent escape sequence based on the specified encoding.

[`CFURLCreateStringByReplacingPercentEscapes(_:_:_:)`](/documentation/CoreFoundation/CFURLCreateStringByReplacingPercentEscapes(_:_:_:))

Creates a new string by replacing any percent escape sequences with their character equivalent.

[`CFURLCreateStringByReplacingPercentEscapesUsingEncoding(_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateStringByReplacingPercentEscapesUsingEncoding(_:_:_:_:))

Creates a new string by replacing any percent escape sequences with their character equivalent.

[`CFURLGetFileSystemRepresentation(_:_:_:_:)`](/documentation/CoreFoundation/CFURLGetFileSystemRepresentation(_:_:_:_:))

Fills a buffer with the file system’s native string representation of a given URL’s path.

[`CFURLGetFSRef(_:_:)`](/documentation/CoreFoundation/CFURLGetFSRef(_:_:))

Converts a given URL to a file or directory object.

[`CFURLGetString(_:)`](/documentation/CoreFoundation/CFURLGetString(_:))

Returns the URL as a `CFString` object.

### Getting URL Properties

[`CFURLGetBaseURL(_:)`](/documentation/CoreFoundation/CFURLGetBaseURL(_:))

Returns the base URL of a given URL if it exists.

[`CFURLGetBytes(_:_:_:)`](/documentation/CoreFoundation/CFURLGetBytes(_:_:_:))

Returns by reference the byte representation of a URL object.

[`CFURLGetByteRangeForComponent(_:_:_:)`](/documentation/CoreFoundation/CFURLGetByteRangeForComponent(_:_:_:))

Returns the range of the specified component in the bytes of a URL.

[`CFURLGetTypeID()`](/documentation/CoreFoundation/CFURLGetTypeID())

Returns the type identifier for the `CFURL` opaque type.

[`CFURLResourceIsReachable(_:_:)`](/documentation/CoreFoundation/CFURLResourceIsReachable(_:_:))

Returns whether the resource pointed to by a file URL can be reached.

### Getting and Setting File System Resource Properties

[`CFURLClearResourcePropertyCache(_:)`](/documentation/CoreFoundation/CFURLClearResourcePropertyCache(_:))

Removes all cached resource values and temporary resource values from the URL object.

[`CFURLClearResourcePropertyCacheForKey(_:_:)`](/documentation/CoreFoundation/CFURLClearResourcePropertyCacheForKey(_:_:))

Removes the cached resource value identified by a given key from the URL object.

[`CFURLCopyResourcePropertiesForKeys(_:_:_:)`](/documentation/CoreFoundation/CFURLCopyResourcePropertiesForKeys(_:_:_:))

Returns the resource values for the properties identified by specified array of keys.

[`CFURLCopyResourcePropertyForKey(_:_:_:_:)`](/documentation/CoreFoundation/CFURLCopyResourcePropertyForKey(_:_:_:_:))

Returns the value of a given resource property of a given URL.

[`CFURLCreateResourcePropertiesForKeysFromBookmarkData(_:_:_:)`](/documentation/CoreFoundation/CFURLCreateResourcePropertiesForKeysFromBookmarkData(_:_:_:))

Returns the resource values for properties identified by a specified array of keys contained in specified bookmark data.

[`CFURLCreateResourcePropertyForKeyFromBookmarkData(_:_:_:)`](/documentation/CoreFoundation/CFURLCreateResourcePropertyForKeyFromBookmarkData(_:_:_:))

Returns the value of a resource property from specified bookmark data.

[`CFURLSetResourcePropertiesForKeys(_:_:_:)`](/documentation/CoreFoundation/CFURLSetResourcePropertiesForKeys(_:_:_:))

Sets the URL’s resource properties for a given set of keys to a given set of values.

[`CFURLSetResourcePropertyForKey(_:_:_:_:)`](/documentation/CoreFoundation/CFURLSetResourcePropertyForKey(_:_:_:_:))

Sets the URL’s resource property for a given key to a given value.

[`CFURLSetTemporaryResourcePropertyForKey(_:_:_:)`](/documentation/CoreFoundation/CFURLSetTemporaryResourcePropertyForKey(_:_:_:))

Sets a temporary resource value on the URL.

### Working with Bookmark Data

[`CFURLCreateBookmarkData(_:_:_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateBookmarkData(_:_:_:_:_:_:))

Returns bookmark data for a URL, created with specified options and resource values.

[`CFURLCreateBookmarkDataFromAliasRecord(_:_:)`](/documentation/CoreFoundation/CFURLCreateBookmarkDataFromAliasRecord(_:_:))

Initializes and returns bookmark data derived from an alias record.

[`CFURLCreateBookmarkDataFromFile(_:_:_:)`](/documentation/CoreFoundation/CFURLCreateBookmarkDataFromFile(_:_:_:))

Initializes and returns bookmark data derived from a file pointed to by a specified URL.

[`CFURLWriteBookmarkDataToFile(_:_:_:_:)`](/documentation/CoreFoundation/CFURLWriteBookmarkDataToFile(_:_:_:_:))

Creates an alias file on disk at a specified location with specified bookmark data.

[`CFURLStartAccessingSecurityScopedResource(_:)`](/documentation/CoreFoundation/CFURLStartAccessingSecurityScopedResource(_:))

In an app that has adopted App Sandbox, makes the resource pointed to by a security-scoped URL available to the app.

[`CFURLStopAccessingSecurityScopedResource(_:)`](/documentation/CoreFoundation/CFURLStopAccessingSecurityScopedResource(_:))

In an app that adopts App Sandbox, revokes access to the resource pointed to by a security-scoped URL.

### Bookmark Data Types

[`CFURLBookmarkCreationOptions`](/documentation/CoreFoundation/CFURLBookmarkCreationOptions)

Type for bookmark data creation options.

[`CFURLBookmarkFileCreationOptions`](/documentation/CoreFoundation/CFURLBookmarkFileCreationOptions)

Type for bookmark file creation options.

[`CFURLBookmarkResolutionOptions`](/documentation/CoreFoundation/CFURLBookmarkResolutionOptions)

Type for bookmark data resolution options.

### Bookmark Data Constants

[Bookmark Data Creation Options](/documentation/CoreFoundation/bookmark-data-creation-options)

Options used when creating bookmark data.

[Bookmark Data Resolution Options](/documentation/CoreFoundation/bookmark-data-resolution-options)

Options used when resolving bookmark data.

### File System Constants

[Common File System Resource Keys](/documentation/CoreFoundation/common-file-system-resource-keys)

Keys that are applicable to file system URLs.

[File Resource Types](/documentation/CoreFoundation/file-resource-types)

Possible values for the [`kCFURLFileResourceTypeKey`](/documentation/CoreFoundation/kCFURLFileResourceTypeKey) key.

[File Property Keys](/documentation/CoreFoundation/file-property-keys)

Keys that apply to properties of files.

[iCloud Constants](/documentation/CoreFoundation/icloud-constants)

These constants can be used to determining whether a file is stored in the cloud and to obtain information about its status.

[Volume Property Keys](/documentation/CoreFoundation/volume-property-keys)

Keys that apply to volumes.

[CFError userInfo Dictionary Keys](/documentation/CoreFoundation/cferror-userinfo-dictionary-keys)

Keys in the userInfo dictionary of a `CFError` object when certain CFURL functions return an error.

### Miscellaneous

[`CFURLComponentType`](/documentation/CoreFoundation/CFURLComponentType)

The types of components in a URL.

[`CFURLPathStyle`](/documentation/CoreFoundation/CFURLPathStyle)

Options you can use to determine how CFURL functions parse a file system path name.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)