manpagez: man pages & more
man xpc_objects(3)
Home | html | info | man

xpc_objects(3)           BSD Library Functions Manual           xpc_objects(3)


NAME

     xpc_objects -- boxed XPC objects reference


SYNOPSIS

     #include <xpc/xpc.h>

     xpc_object_t
     xpc_null_create(void);

     xpc_object_t
     xpc_bool_create(bool value);

     bool
     xpc_bool_get_value(xpc_object_t xbool);

     xpc_object_t
     xpc_int64_create(int64_t value);

     int64_t
     xpc_int64_get_value(xpc_object_t xint);

     xpc_object_t
     xpc_uint64_create(uint64_t value);

     uint64_t
     xpc_uint64_get_value(xpc_object_t xuint);

     xpc_object_t
     xpc_double_create(double value);

     double
     xpc_double_get_value(xpc_object_t xdouble);

     xpc_object_t
     xpc_date_create(int64_t interval);

     xpc_object_t
     xpc_date_create_from_current(void);

     int64_t
     xpc_date_get_value(xpc_object_t xdate);

     xpc_object_t
     xpc_data_create(const void *bytes, size_t length);

     xpc_object_t
     xpc_data_create_with_dispatch_data(dispatch_data_t ddata);

     size_t
     xpc_data_get_length(xpc_object_t xdata);

     const void *
     xpc_data_get_bytes_ptr(xpc_object_t xdata);

     size_t
     xpc_data_get_bytes(xpc_object_t xdata, void *buffer, size_t off,
         size_t length);

     xpc_object_t
     xpc_string_create(const char *string);

     xpc_object_t
     xpc_string_create_with_format(const char *fmt, ...);

     xpc_object_t
     xpc_string_create_with_format_and_arguments(const char *fmt, va_list ap);

     size_t
     xpc_string_get_length(xpc_object_t xstring);

     const char *
     xpc_string_get_string_ptr(xpc_object_t xstring);

     xpc_object_t
     xpc_uuid_create(const uuid_t uuid);

     const uint8_t *
     xpc_uuid_get_bytes(xpc_object_t xuuid);

     xpc_object_t
     xpc_fd_create(int fd);

     int
     xpc_fd_dup(xpc_object_t xfd);

     xpc_object_t
     xpc_shmem_create(void *region, size_t length);

     size_t
     xpc_shmem_map(xpc_object_t xshmem, void **region);


DESCRIPTION

     Most XPC objects are boxed representations of primitive C language types
     or low-level operating system handles. These boxed objects are immutable.
     In general, the getter methods for each object type will check to see if
     the given object is of the proper type and, if it is not, will return a
     sensible default value as described in xpc_object(3).  If an improper
     object is given to another type of method, the behavior is undefined.

     See xpc_object(3) for information about functions common to all XPC
     objects.


PRIMITIVE TYPES

     XPC objects can encapsulate a wide variety of primitive C language types:

   INTEGERS
     Boxed representations of 64-bit wide signed and unsigned integer types
     may be created with xpc_int64_create() and xpc_uint64_create() respec-
     tively. The boxed values may be retrieved using xpc_int64_get_value() and
     xpc_uint64_get_value().

   FLOATING POINT
     Boxed representations of double-precision floating point value represen-
     tations may be created with the xpc_double_create() function and
     retrieved with the xpc_double_get_value() function.

   DATES
     Boxed representations of date and time values, expressed as an integral
     number of nanoseconds before or after the Unix epoch, can be created with
     the xpc_date_create() function and retrieved with the
     xpc_date_get_value() function.  A date object representing the current
     date may be created with xpc_date_create_from_current() convenience func-
     tion.

   NULL AND BOOLEAN SINGLETONS
     Boxed representations of null and Boolean values are expressed as XPC
     object singletons. The xpc_bool_create() function returns one of two con-
     stant singleton Boolean values:
           o   XPC_BOOL_TRUE
           o   XPC_BOOL_FALSE

     The singleton values may be compared using direct pointer equality. Simi-
     larly, no type checking is required when retreiving these values from
     collections:

           xpc_object_t xbool = xpc_dictionary_get_value(dictionary, "key");
           if (xbool == XPC_BOOL_TRUE) {
                   // Handle the true case.
           } else if (xbool == XPC_BOOL_FALSE)
                   // Handle the false case.
           } else {
                   // Handle the case where there was a type mismatch or where there was no
                   // value for the key "key".
           }

     The xpc_null_create() function returns a constant singleton representa-
     tion of a null value.  There is currently no defined constant for this
     singleton.

     It is safe to call xpc_retain(3) and xpc_release(3) on Boolean and null
     objects.


DATA, STRINGS AND UUIDS

   DATA
     Boxed representations of arbitrary byte values may be created with the
     xpc_data_create() function which takes a pointer to a buffer and length.
     A pointer to the underlying storage of the data object may be obtained
     using xpc_data_get_bytes_ptr().

     Important: This pointer is only valid for the lifetime of the data
     object. The underlying storage of the pointer value must not be modified
     by the caller. When ARC is enabled, care needs to be taken that the data
     object is not released prematurely, see xpc_object(3) for details.

     The contents of a data object may be copied to an external buffer using
     the xpc_data_get_bytes() function. This function takes a pointer to a
     buffer of size length to which the data will be copied.  The caller may
     also specify a non-zero offset into the source data at which to start the
     copy. The return value of this function is the number of bytes that were
     copied into the buffer.  If the destination buffer is smaller than the
     size of the source data, as many bytes as possible will be copied and the
     return value will be equal to the number of bytes specified in length.

     The underlying size of the data value may be determined using the
     xpc_data_get_length() function.

     When creating a data object, the contents of the provided buffer are
     copied into internal storage. If the caller wishes to avoid a copy, the
     buffer may first be encapsulated in a dispatch_data_t object and passed
     to xpc_data_create_with_dispatch_data().  See dispatch_data_create(3) for
     more information.

     Note: When the time comes to send a message, the XPC runtime will serial-
     ize the object graph, which will result in a copy of any data objects
     contained therein. This can be very costly for large amounts of data. To
     completely avoid any copying in the message-send path for large data
     objects (where "large" is defined by the system), you may create a data
     object using dispatch_data_create(3) with the
     DISPATCH_DATA_DESTRUCTOR_MUNMAP destructor specified. This will hint to
     the system that the data buffer may be safely shared copy-on-write with
     the recipient of the message.

     Important: Data objects created with the intention of eliminating copies
     can only be safely created VM objects that the caller owns. Buffers
     returned by malloc(3) do NOT satisfy this condition as the caller does
     not own the underlying VM object associated with an allocation returned
     by malloc(3).  Similarly, if the caller receives a buffer from an exter-
     nal subsystem across an API boundary, this buffer is not owned by the
     caller unless part of the API contract specifies how the buffer should
     have been created. Sending buffers not owned by the caller in this way
     can result in information leakage from elsewhere on the heap.

   STRINGS
     Boxed representations of C string values may be created using the
     xpc_string_create() function.  The XPC framework assumes all strings are
     encoded as UTF-8 and does not support any other encodings. A pointer to
     the C string representation of a value may be obtained using
     xpc_string_get_string_ptr().

     Important: This pointer is only valid for the lifetime of the string
     object. The underlying storage of the pointer value must not be modified
     by the caller.  When ARC is enabled, care needs to be taken that the
     string object is not released prematurely, see xpc_object(3) for details.

     The length of the C string value may be determined using the
     xpc_string_get_length() function. This length does not include the NUL
     terminator character, similar to strlen(3).

     String objects may also be constructed from printf(3) -style format
     strings using the xpc_string_create_with_format() function.  Addition-
     ally, the xpc_string_create_with_format_and_arguments() function allows
     the caller to pass an existing va_list argument with which to construct
     the formatted string.

   UUIDs
     Boxed representations of UUID byte values may be created using
     xpc_uuid_create().  See uuid(3) for more information.  A pointer to stor-
     age for the underlying UUID value may be obtained using
     xpc_uuid_get_bytes().  The returned pointer may be safely passed to the
     relevant uuid(3) functions.

     Important: This pointer is only valid for the lifetime of the UUID
     object. The underlying storage of the UUID value must not be modified by
     the caller. When ARC is enabled, care needs to be taken that the UUID
     object is not released prematurely, see xpc_object(3) for details.

     The pattern of returning a pointer instead of copying the result into a
     uuid_t enables some convenient code simplification. For example:

           if (uuid_compare(xpc_uuid_get_bytes(uuid_object), expected_uuid) == 0) {
                   // They are the same.
           }


OUT-OF-LINE TYPES

     Boxed representations of low-level operating system primitives such as
     file descriptors and shared memory regions may be created and shared
     between processes as part of an XPC dictionary that is sent as a message.

   FILE DESCRIPTORS
     Boxed representations of file descriptors may be created using the
     xpc_fd_create() function.  Once created, there is no way to retrieve the
     original file descriptor from the boxed representation. This function
     performs the equivalent of a dup(2) on the descriptor, and thus it is
     safe to call close(2) on the descriptor after boxing it.

     The xpc_fd_dup() function can be used to create a new file descriptor
     from a boxed representation in a similar manner to dup(2).  The caller is
     responsible for calling close(2) on the descriptor returned by
     xpc_fd_dup().

     Multiple calls to xpc_fd_dup() will produce multiple unique file descrip-
     tor values.  If a failure occurs (i.e. process file descriptor table is
     full), the invalid file descriptor value -1 will be returned.

     Important: When file descriptors are copied with dup(2), they share some
     state, including flags and lseek(2) file offset. The same sharing obtains
     when these boxing and unboxing functions create copies of file descrip-
     tors, and when a boxed representation of a file descriptor is sent to
     another process using XPC.

     For example, suppose one process opens a file and sends the file descrip-
     tor to another process. Then, the first process uses read(2) to read the
     first 100 bytes from the file. If the second process then calls read(2)
     on the descriptor that it received from the first process, the data it
     reads will start at the 101st byte of the file, not the 1st.

     This is not usually the desired behavior.

     Therefore, if you wish to send a file to another process, it is best not
     to box one shared file descriptor. Instead you should open(2) the file
     afresh for each other process you wish to share with.

   SHARED MEMORY
     Boxed representations of shared memory regions allocated using mmap(2)
     with the MAP_SHARED flag passed in the flags argument may be created
     using the xpc_shmem_create() function. Memory objects created using
     malloc(3) are not supported.  The region argument is a pointer to the
     beginning of the shared region and the length argument specifies the
     length of the shared region.

     The recipient of a shared memory object may map the underlying region
     into its address space using the xpc_shmem_map() function.  As with file
     descriptor objects, each call to this function returns a distinct but
     equivalent mapping. On output, the region argument will point to the
     address of the new mapping, and the return value will be the size of that
     mapping. This size will always be an integral page size, as it is not
     possible to share memory regions at less than page granularity. The
     caller is responsible for unmapping the region with munmap(2).  If the
     mapping operation failed, 0 will be returned.

     New mappings will be created with the maximum permission as specified by
     the creator of the region. Currently, there is no direct way to modify
     the permissions that the recipient of a region will have. If the caller
     wishes to maintain read-write permissions to a region, for example, while
     giving others read-only access, it can create an equivalent mapping with
     the desired permissions using a combination of
     mach_make_memory_entry_64() and mach_vm_remap().  The details of this
     procedure are left as an exercise to the reader.

     Certain operations that can operate on subranges of a region, such as
     vm_copy(), vm_read(), and vm_write(), may fragment the underlying repre-
     sentation of a memory region in order to avoid physical copies. After
     this fragmentation has occurred, it is not safe to create a shared memory
     object out of the region. For this reason, it is recommended that any
     such operations be delayed until after the shared memory object has been
     created, as the existence of the object will hint to the VM that the
     region's internal representation should be kept contiguous. Note that
     this will necessarily defeat these optimizations and force physical
     copies of subranges.


SEE ALSO

     xpc_object(3), xpc_dictionary_create(3), xpc_array_create(3),
     xpc_connection_create(3), dispatch_data_create(3), printf(3), uuid(3),
     dup(2), close(2)

Darwin                           1 July, 2011                           Darwin

Mac OS X 10.13.1 - Generated Wed Nov 8 19:15:36 CST 2017
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.