<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from DB_File/mod.rs (xs_put). Do not edit. -->

```{index} single: put (DB_File)
```
```{index} single: DB_File::put
```

# put

Store a value under a key, with flags that say where and whether.

## Synopsis

```perl
my $status = $db->put($key, $value);
$status = $db->put($key, $value, R_NOOVERWRITE);
```

## What you get back

0 when the value was stored, 1 when `R_NOOVERWRITE` found the key
already there, -1 for an error.

## Flags

- none - store the value, replacing the key's; in an `R_DUP`
  database, add it after the key's other values.
- `R_NOOVERWRITE` - store only if the key is not there yet.
- `R_CURSOR` - replace the value the database's cursor stands on; the
  key given is ignored.
- `R_SETCURSOR` - store, then set the cursor on the key (its first
  value, in an `R_DUP` database).
- `R_IAFTER`, `R_IBEFORE` - put a new array element after or before
  element `$key`, the ones after it moving up; in an `R_DUP` database,
  a new value after or before the key's first. `$key` must be a
  variable: the method writes it back.

## Examples

```perl
print $db->put('a', 1);                   # 0
print $db->put('a', 2, R_NOOVERWRITE);    # 1, and 'a' is still 1
```

Insert into an array:

```perl
@lines = qw(one three);
my $i = 0;
$db->put($i, 'two', R_IAFTER);            # one two three
```

## Edge cases

- `R_IAFTER` and `R_IBEFORE` leave `$key` as it was; they return -1 for
  an element past the end or created empty, and in a hash database
  without `R_DUP` (`$DB_File::Error` then says the flag is illegal).
- `R_CURSOR` with no cursor set yet returns -1. After a delete at the
  cursor, a `$DB_HASH` or `$DB_BTREE` database returns `-30987`
  (Berkeley DB's `DB_NOTFOUND`) and stores nothing, while an array
  gets the deleted element back with the new value.
- A fixed-length array refuses a value longer than its records: -1,
  with `$DB_File::Error` giving both lengths.
- On a database opened read-only it returns -1.

## Differences from upstream

Fully compatible with upstream. Covered by
`t/81-xs-native/DB_File/010-phenotype.t`.

## See also

- `get` - reads a value back
- `del` - removes a key, or the item at the cursor
- `seq` - sets the cursor `R_CURSOR` writes at