---
name: "pmem2_source_from_handle"
section: "3"
platform: "linux"
package: "libpmem2-dev"
version: "1.13.1-1.1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pmem2_source_from_fd"
---

# pmem2\_source\_from\_handle(3)

creates or deletes an instance of persistent memory data source

Part of [pmem2\_source\_from\_fd(3)](/pmem2_source_from_fd/3.md).

## NAME

**pmem2\_source\_from\_fd**(), **pmem2\_source\_from\_handle**(), **pmem2\_source\_delete**() - creates or deletes an instance of persistent memory data source

## SYNOPSIS

-

  ```
  #include <libpmem2.h>
  int pmem2_source_from_fd(struct pmem2_source *src, int fd);
  int pmem2_source_from_handle(struct pmem2_source *src, HANDLE handle); /* Windows only */
  int pmem2_source_delete(struct pmem2_source **src);
  ```

## DESCRIPTION

On Linux the **pmem2\_source\_from\_fd**() function validates the file descriptor and instantiates a new \*struct pmem2\_source\*\* object describing the data source.

On Windows the **pmem2\_source\_from\_fd**() function converts a file descriptor to a file handle (using \*\*\_get\_osfhandle**()), and passes** **it to** pmem2\_source\_from\_handle**(). By default** \_get\_osfhandle**() calls abort() in case of invalid file** **descriptor, but this behavior can be suppressed by** \_set\_abort\_behavior**() and** SetErrorMode\*\*() functions. Please check MSDN documentation for more information about Windows CRT error handling.

*fd* must be opened with *O\_RDONLY* or *O\_RDWR* mode, but on Windows it is not validated.

If *fd* is invalid, then the function fails.

The **pmem2\_source\_from\_handle**() function validates the handle and instantiates a new \*struct pmem2\_source **object describing the** **data source. If** ***handle*** **is** ***INVALID\_HANDLE\_VALUE*****,** **then the function fails. The handle has to be created with an access** **mode of** ***GENERIC\_READ*** **or** ***(GENERIC\_READ \|*** ***GENERIC\_WRITE)*****. For details please see the** CreateFile\*\*() documentation.

The **pmem2\_source\_delete**() function frees *\*src* returned by **pmem2\_source\_from\_fd**() or **pmem2\_source\_from\_handle**() and sets *\*src* to NULL. If *\*src* is NULL, no operation is performed.

## RETURN VALUE

The **pmem2\_source\_from\_fd**() and **pmem2\_source\_from\_handle**() functions return 0 on success or a negative error code on failure.

The **pmem2\_source\_delete**() function always returns 0.

## ERRORS

The **pmem2\_source\_from\_fd**()/**pmem2\_source\_from\_handle**() functions can fail with the following errors:

- •

  **PMEM2\_E\_INVALID\_FILE\_HANDLE** - *fd* is not an open and valid file descriptor. On Windows the function can **abort**() on this failure based on CRT’s abort() behavior.

- •

  **PMEM2\_E\_INVALID\_FILE\_HANDLE** - *fd* is opened in O\_WRONLY mode.

On Linux:

- •

  **PMEM2\_E\_INVALID\_FILE\_TYPE** - *fd* points to a directory, block device, pipe, or socket.

- •

  **PMEM2\_E\_INVALID\_FILE\_TYPE** - *fd* points to a character device other than Device DAX.

On Windows:

- •

  **PMEM2\_E\_INVALID\_FILE\_TYPE** - *handle* points to a resource that is not a regular file.

On Windows **pmem2\_source\_from\_fd**() can return all errors from the underlying **pmem2\_source\_from\_handle**() function.

The **pmem2\_source\_from\_handle**() can return the following errors:

- •

  **PMEM2\_E\_INVALID\_FILE\_HANDLE** - *handle* points to a resource that is not a file.

- •

  **PMEM2\_E\_INVALID\_FILE\_TYPE** - *handle* points to a directory.

The **pmem2\_source\_from\_fd**() and **pmem2\_source\_from\_handle**() functions can also return **-ENOMEM** in case of insufficient memory to allocate an instance of *struct pmem2\_source*.

## CAVEATS

On non-DAX Windows volumes, *fd*/*handle* must remain open while the mapping is in use.

## SEE ALSO

[**errno**(3)](/errno/3.md), [**pmem2\_map\_new**(3)](/pmem2_map_new/3.md), [**libpmem2**(7)](/libpmem2/7.md) and **\<https://pmem.io\>**