sys/man/3/segment

   1 .TH SEGMENT 3
   2 .SH NAME
   3 segment \- long lived memory segments
   4 .SH SYNOPSIS
   5 .nf
   6 .B bind '#g' /mnt/segment
   7
   8 .BI #g/ seg1
   9 .BI #g/ seg1 /ctl
  10 .BI #g/ seg1 /data
  11 .BI #g/ seg2
  12 .BI #g/ seg2 /ctl
  13 .BI #g/ seg2 /data
  14  ...
  15 .fi
  16 .SH DESCRIPTION
  17 .PP
  18 The
  19 .I segment
  20 device provides a 2-level file system representing
  21 long-lived sharable segments that processes may
  22 .IR segattach (2).
  23 The name of the directory is the
  24 .I class
  25 argument to
  26 .IR segattach .
  27 .PP
  28 New segments are created under the top level
  29 using
  30 .B create
  31 (see
  32 .IR open (2)).
  33 The
  34 .B DMDIR
  35 bit must be set in the permissions.
  36 .IR Remove (2)'ing
  37 the directory makes the segment no longer
  38 available for
  39 .IR segattach .
  40 However, the segment will continue to exist until all
  41 processes using it either exit or
  42 .I segdetach
  43 it.
  44 .PP
  45 Within each segment directory are two files,
  46 .B data
  47 and
  48 .BR ctl .
  49 Reading and writing
  50 .B data
  51 affects the contents of the segment.
  52 Reading and writing
  53 .B ctl
  54 retrieves and sets the segment's properties.
  55 .PP
  56 There is only one control message, which sets the segment's
  57 virtual address and length in bytes:
  58 .EX
  59         va \fIaddress length\fP
  60 .EE
  61 .I Address
  62 is automatically rounded down to a page boundary and
  63 .I length
  64 is rounded up to end the segment at a page boundary.
  65 The segment will reside at the same virtual address in
  66 all processes sharing it.
  67 When the segment
  68 is attached using
  69 .IR segattach,
  70 the address and length arguments are ignored in the call;
  71 they are defined only by the
  72 .B va
  73 control message.
  74 Once the address and length are set, they cannot be reset.
  75 .PP
  76 Reading the control file
  77 returns a message of the same format with the segment's actual
  78 start address and length.
  79 .PP
  80 Opening
  81 .B data
  82 or reading
  83 .B ctl
  84 before setting the virtual address yields the error
  85 ``segment not yet allocated''.
  86 .PP
  87 The permissions check when
  88 .IR segattach ing
  89 is equivalent to the one performed when opening
  90 .B data
  91 with mode ORDWR.
  92 .SH EXAMPLE
  93 .PP
  94 Create a one megabyte segment at address 0x10000000:
  95 .EX
  96         % bind '#g' /mnt/segment
  97         % mkdir /mnt/segment/example
  98         % echo 'va 0x10000000 0x100000' > /mnt/segment/example/ctl
  99 .EE
 100 .PP
 101 Put the string ``hi mom'' at the start of the segment:
 102 .EX
 103         % echo -n hi mom > /mnt/segment/example/data
 104 .EE
 105 .PP
 106 Attach the segment to a process:
 107 .EX
 108 {
 109         ulong va;
 110
 111         va = segattach(0, "example", 0, 0);
 112 }
 113 .EE
 114 .SH "SEE ALSO
 115 .IR segattach (2)
 116 .SH SOURCE
 117 .B /sys/src/9/port/devsegment.c