.\" Man page generated from reStructuredText.
.
.TH "PLAINBOX_SESSION_SHARE" "7" "January 05, 2016" "0.25" "Plainbox"
.SH NAME
PLAINBOX_SESSION_SHARE \- per-session runtime shared-state directory
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
Saving files to session share directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\(ga\(gacommand: do\-something > $PLAINBOX_SESSION_SHARE/some\-action.log\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Loading files from session\-share directory:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\(ga\(gacommand: cat $PLAINBOX_SESSION_SHARE/some\-action.log\(ga\(ga
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
Plainbox sessions allow jobs to communicate by referring to the
$PLAINBOX_SESSION_SHARE environment variable. Files generated
therein are explicitly meant to be accessible to all the other jobs
participating in the session.
.SS Typical Use Cases
.sp
Typically a session will involve one or more pairs of jobs such as:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
id: some\-action
plugin: shell
summary: do something and save the log file to disk
commmand: do\-something > $PLAINBOX_SESSION_SHARE/some\-action.log

id: some\-action\-attachment
plugin: attachment
summary: log file of the do\-something command
command: cat $PLAINBOX_SESSION_SHARE/some\-action.log
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The job \fBsome\-action\fP will use the \fBdo\-something\fP executable
to perform some tests. The log file of that action will be saved on
the device executing the test, in the directory exposed through the
environment variable \fB$PLAINBOX_SESSION_SHARE\fP\&.
.sp
The \fBsome\-action\-attachment\fP job will use that same directory and
the agreed\-upon name of the log file and \fBcat\fP (1) it, which coupled
with the plugin type \fIshell\fP will cause Plainbox to attach the log
file to the resulting document.
.SS Checkbox Compatibility
.sp
Jobs designed to work with pre\-Plainbox\-based Checkbox may still refer
to the old, somewhat confusing, environment variable
\fB$CHECKBOX_DATA\fP\&. It points to the same directory.
.SS Multi\-Node Sessions
.sp
When a test session involves multiple devices this directory is
separately instantiated for each device. Jobs executing on separate
devices cannot use this facility to communicate. If communication
is required jobs are expected to use the LAVA\-inspired, MPI\-based
communication API. For details see \fBplainbox\-multi\-node\-api\fP (7)
.SH BUGS
.sp
Within the session directory the name of this directory is still
\fBCHECKBOX_DATA\fP (literally, this is not a variable name). It may be changed
at any point in time since jobs cannot form any meaningful paths to this
directory without referring to either \fB$PLAINBOX_SESSION_SHARE\fP or
\fB$CHECKBOX_DATA\fP
.SH SEE ALSO
.sp
\fBPLAINBOX_PROVIDER_DATA\fP, \fBCHECKBOX_DATA\fP
.SH AUTHOR
Zygmunt Krynicki & Checkbox Contributors
.SH COPYRIGHT
2012-2014 Canonical Ltd
.\" Generated by docutils manpage writer.
.