.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 11, 2016
.Dt PSETZONEID 3PROC
.Os
.Sh NAME
.Nm Psetzoneid
.Nd change processes zone id
.Sh LIBRARY
.Lb libproc
.Sh SYNOPSIS
.In libproc.h
.Ft int
.Fo Psetzoneid
.Fa "struct ps_prochandle *P"
.Fa "zoneid_t zoneid"
.Fc
.Sh DESCRIPTION
The
.Fn Psetzoneid
function moves the process handle
.Fa P
into the zone specified by
.Fa zoneid .
A process that is in the non-global zone may only move between the
global zone and its original zone.
A process that is in the global zone may not use this interface to enter a
non-global zone.
This function will fail if called from a non-global zone.
This function only manipulates the processes credentials.
.Pp
Care should be taken when moving a process around temporarily, such that
if the process that is manipulating
.Fa P
dies, it does not cause
.Fa P
to resume running while still in the global zone.
It is suggested that the
.Sy PR_KLC
flag is set with
.Xr Psetflags 3PROC
which will cause the process to terminate if the process that holds
.Fa P
unexpectedly terminates.
See
.Xr proc 5
for more information on the
.Sy PR_KLC
flag.
.Pp
Note, only active processes may change their zone.
It is an error to call this function on process handles that correspond to core
files, zombie processes, or files.
.Sh RETURN VALUES
Upon successful completion, the
.Fn Psetzoneid
function returns
.Sy 0
and changes the zone for
.Fa P .
Otherwise,
.Sy -1
is returned and
.Sy errno
is set.
.Sh ERRORS
For a full list of possible errors see the
.Sy DIAGNOSTICS
section in
.Xr proc 5 .
.Pp
The
.Fn Psetzoneid
function will fail if:
.Bl -tag -width Er
.It Er EINVAL
.Fa zoneid
does not correspond to an existing zone or the zone id is not the global
zone or the original zone of
.Fa P .
.It Er EPERM
The caller does not hold the required privileges for zone configuration.
.El
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
See
.Sy LOCKING
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr libproc 3LIB ,
.Xr proc 5 ,
.Xr privileges 7 ,
.Xr zones 7